An open source design system that's fully customizable and agent ready
TypeScript
feat(playground): switch URL compression from lz-string to fflate (#2648)
Cindy Zhang47441155e5e5
diff --git a/apps/docsite/package.json b/apps/docsite/package.jsonindex 2620a24601..20aa46be69 100644--- a/apps/docsite/package.json+++ b/apps/docsite/package.json@@ -27,6 +27,7 @@"@xds/theme-neutral": "*","@xds/theme-stone": "*","@xds/theme-y2k": "*",+ "fflate": "^0.8.2","lucide-react": "^1.17.0","lz-string": "^1.5.0","mcp-handler": "^1.1.0",diff --git a/apps/docsite/src/__tests__/compress.test.ts b/apps/docsite/src/__tests__/compress.test.tsnew file mode 100644index 0000000000..2f785946be--- /dev/null+++ b/apps/docsite/src/__tests__/compress.test.ts@@ -0,0 +1,39 @@+// Copyright (c) Meta Platforms, Inc. and affiliates.++/**+ * @file Compression round-trip and backward-compat tests.+ * Run: pnpm -F @xds/docsite test+ */++import {describe, it, expect} from 'vitest';+import {compressCode, decompressCode} from '../lib/compress';+import {compressToEncodedURIComponent} from 'lz-string';++describe('compress', () => {+ const SAMPLE = `import {XDSButton} from '@xds/core/Button';+export default function Demo() {+ return <XDSButton label="Hello" variant="primary" />;+}`;++ it('round-trips code through compress/decompress', () => {+ const compressed = compressCode(SAMPLE);+ const decompressed = decompressCode(compressed);+ expect(decompressed).toBe(SAMPLE);+ });++ it('produces shorter output than lz-string', () => {+ const fflateLen = compressCode(SAMPLE).length;+ const lzLen = compressToEncodedURIComponent(SAMPLE).length;+ expect(fflateLen).toBeLessThan(lzLen);+ });++ it('decompresses legacy lz-string URLs', () => {+ const lzCompressed = compressToEncodedURIComponent(SAMPLE);+ const decompressed = decompressCode(lzCompressed);+ expect(decompressed).toBe(SAMPLE);+ });++ it('returns null for garbage input', () => {+ expect(decompressCode('not-valid-at-all-!!!!')).toBeNull();+ });+});diff --git a/apps/docsite/src/app/playground/PlaygroundClient.tsx b/apps/docsite/src/app/playground/PlaygroundClient.tsxindex 700b37336c..f625667de4 100644--- a/apps/docsite/src/app/playground/PlaygroundClient.tsx+++ b/apps/docsite/src/app/playground/PlaygroundClient.tsx@@ -27,11 +27,8 @@ import {useSearchParams} from 'next/navigation';import dynamic from 'next/dynamic';import {loader} from '@monaco-editor/react';import * as stylex from '@stylexjs/stylex';-import {- compressToEncodedURIComponent,- decompressFromEncodedURIComponent,-} from 'lz-string';import {XDSAppShell} from '@xds/core/AppShell';+import {compressCode, decompressCode} from '../../lib/compress';import {XDSButton} from '@xds/core/Button';import {XDSLink} from '@xds/core/Link';import {XDSHStack, XDSVStack} from '@xds/core/Layout';@@ -158,14 +155,14 @@ function getInitialCode(): string {return DEFAULT_CODE;}try {- return decompressFromEncodedURIComponent(compressed) || DEFAULT_CODE;+ return decompressCode(compressed) || DEFAULT_CODE;} catch {return DEFAULT_CODE;}}function updateURL(code: string) {- const compressed = compressToEncodedURIComponent(code);+ const compressed = compressCode(code);window.history.replaceState(null, '', `#code=${compressed}`);}diff --git a/apps/docsite/src/components/playgroundLink.ts b/apps/docsite/src/components/playgroundLink.tsindex 25fcfd4b57..af8cfcd94c 100644--- a/apps/docsite/src/components/playgroundLink.ts+++ b/apps/docsite/src/components/playgroundLink.ts@@ -1,6 +1,6 @@// Copyright (c) Meta Platforms, Inc. and affiliates.-import {compressToEncodedURIComponent} from 'lz-string';+import {compressCode} from '../lib/compress';import {stripCodeExampleCopyrightHeader} from '../lib/codeExamples';/**@@ -12,7 +12,7 @@ import {stripCodeExampleCopyrightHeader} from '../lib/codeExamples';*/export function buildPlaygroundHref(source: string, theme?: string): string {const cleanedSource = stripCodeExampleCopyrightHeader(source);- const compressed = compressToEncodedURIComponent(cleanedSource);+ const compressed = compressCode(cleanedSource);const query = theme ? `?theme=${encodeURIComponent(theme)}` : '';return `/playground${query}#code=${compressed}`;}diff --git a/apps/docsite/src/lib/compress.ts b/apps/docsite/src/lib/compress.tsnew file mode 100644index 0000000000..80955c4d0b--- /dev/null+++ b/apps/docsite/src/lib/compress.ts@@ -0,0 +1,69 @@+// Copyright (c) Meta Platforms, Inc. and affiliates.++/**+ * @file compress.ts+ * @input Raw playground source code (string)+ * @output URL-safe compressed string (base64url-encoded deflate)+ * @position lib/ — shared compression utilities for playground URL encoding.+ *+ * Uses fflate (deflate level 9 + base64url) which produces ~30-40% shorter+ * output than lz-string for typical JSX/TSX playground code.+ *+ * Decompression supports both the new fflate format and legacy lz-string URLs+ * so existing shared links continue to work.+ */++import {deflateSync, inflateSync} from 'fflate';+import {decompressFromEncodedURIComponent} from 'lz-string';++/**+ * Compress source code to a URL-safe string (base64url-encoded deflate).+ */+export function compressCode(code: string): string {+ const encoded = new TextEncoder().encode(code);+ const deflated = deflateSync(encoded, {level: 9});+ return bufferToBase64Url(deflated);+}++/**+ * Decompress a URL param back to source code.+ * Handles both new (fflate/base64url) and legacy (lz-string) formats.+ */+export function decompressCode(compressed: string): string | null {+ // Try fflate first (base64url → inflate)+ try {+ const bytes = base64UrlToBuffer(compressed);+ const inflated = inflateSync(bytes);+ return new TextDecoder().decode(inflated);+ } catch {+ // Fall through to lz-string for legacy URLs+ }++ // Legacy: lz-string encoded URI component+ try {+ return decompressFromEncodedURIComponent(compressed);+ } catch {+ return null;+ }+}++function bufferToBase64Url(bytes: Uint8Array): string {+ let binary = '';+ for (let i = 0; i < bytes.length; i++) {+ binary += String.fromCharCode(bytes[i]);+ }+ return btoa(binary)+ .replace(/\+/g, '-')+ .replace(/\//g, '_')+ .replace(/=+$/g, '');+}++function base64UrlToBuffer(str: string): Uint8Array {+ const base64 = str.replace(/-/g, '+').replace(/_/g, '/');+ const binary = atob(base64);+ const bytes = new Uint8Array(binary.length);+ for (let i = 0; i < binary.length; i++) {+ bytes[i] = binary.charCodeAt(i);+ }+ return bytes;+}diff --git a/packages/cli/templates/blocks/components/FieldStatus/FieldStatusShowcase.doc.mjs b/packages/cli/templates/blocks/components/FieldStatus/FieldStatusShowcase.doc.mjsindex 5ca767e80a..274888c604 100644--- a/packages/cli/templates/blocks/components/FieldStatus/FieldStatusShowcase.doc.mjs+++ b/packages/cli/templates/blocks/components/FieldStatus/FieldStatusShowcase.doc.mjs@@ -11,5 +11,5 @@ export const doc = {isReady: true,isShowcase: true,aspectRatio: 16 / 9,- componentsUsed: ['Field', 'FieldStatus'],+ componentsUsed: ['FieldStatus', 'Layout'],};diff --git a/packages/cli/templates/blocks/components/FieldStatus/FieldStatusShowcase.tsx b/packages/cli/templates/blocks/components/FieldStatus/FieldStatusShowcase.tsxindex 21eedc0cb8..99cfc2c2ea 100644--- a/packages/cli/templates/blocks/components/FieldStatus/FieldStatusShowcase.tsx+++ b/packages/cli/templates/blocks/components/FieldStatus/FieldStatusShowcase.tsx@@ -2,7 +2,7 @@'use client';-import {XDSFieldStatus} from '@xds/core/Field';+import {XDSFieldStatus} from '@xds/core/FieldStatus';import {XDSVStack} from '@xds/core/Layout';export default function FieldStatusShowcase() {diff --git a/packages/core/package.json b/packages/core/package.jsonindex d47013173a..1a6edf4dc6 100644--- a/packages/core/package.json+++ b/packages/core/package.json@@ -228,6 +228,11 @@"types": "./dist/Field/index.d.ts","default": "./dist/Field/index.js"},+ "./FieldStatus": {+ "source": "./src/FieldStatus/index.ts",+ "types": "./dist/FieldStatus/index.d.ts",+ "default": "./dist/FieldStatus/index.js"+ },"./FileInput": {"source": "./src/FileInput/index.ts","types": "./dist/FileInput/index.d.ts",diff --git a/packages/core/src/CheckboxInput/XDSCheckboxInput.tsx b/packages/core/src/CheckboxInput/XDSCheckboxInput.tsxindex 5a14fba1ff..24bb763911 100644--- a/packages/core/src/CheckboxInput/XDSCheckboxInput.tsx+++ b/packages/core/src/CheckboxInput/XDSCheckboxInput.tsx@@ -39,7 +39,7 @@ import {} from '../theme/tokens.stylex';import type {XDSBaseProps} from '../XDSBaseProps';import {XDSFieldLabel} from '../Field/XDSFieldLabel';-import {XDSFieldStatus} from '../Field/XDSFieldStatus';+import {XDSFieldStatus} from '../FieldStatus/XDSFieldStatus';import type {XDSIconType} from '../Icon';import type {XDSInputStatus} from '../Field/types';import {XDSSpinner} from '../Spinner';diff --git a/packages/core/src/Field/FieldStatus.doc.mjs b/packages/core/src/Field/FieldStatus.doc.mjsdeleted file mode 100644index f9eb5b48bc..0000000000--- a/packages/core/src/Field/FieldStatus.doc.mjs+++ /dev/null@@ -1,81 +0,0 @@-// Copyright (c) Meta Platforms, Inc. and affiliates.--/** @type {import('../docs-types').ComponentDoc} */--export const docs = {- name: 'FieldStatus',- subComponentOf: 'Field',- displayName: 'Field Status',- isHiddenFromOverview: true,- description: 'Status message component for form field validation feedback.',- props: [- {- name: 'type',- type: "'error' | 'warning' | 'success'",- description: 'Status type.',- required: true,- },- {- name: 'message',- type: 'string',- description: 'Status message text.',- required: true,- },- {- name: 'id',- type: 'string',- description: 'ID for aria-describedby association.',- },- {- name: 'variant',- type: "'attached' | 'detached'",- description: 'Visual variant — attached overlaps the input, detached floats below.',- default: "'attached'",- },- ],-};--export const docsZh = {- name: 'FieldStatus',- isHiddenFromOverview: true,- displayName: 'Field Status',- description: '用于表单字段验证反馈的状态消息组件。',- props: [- {- name: 'type',- type: "'error' | 'warning' | 'success'",- description: '状态类型。',- required: true,- },- {- name: 'message',- type: 'string',- description: '状态消息文本。',- required: true,- },- {- name: 'id',- type: 'string',- description: '用于 aria-describedby 关联的 ID。',- },- {- name: 'variant',- type: "'attached' | 'detached'",- description: '视觉变体 - attached 覆盖在输入框上,detached 浮动在下方。',- default: "'attached'",- },- ],-};--export const docsDense = {- name: 'FieldStatus',- isHiddenFromOverview: true,- displayName: 'Field Status',- description: 'Status message for form field validation feedback.',- propDescriptions: {- type: 'Status type.',- message: 'Status message text.',- id: 'ID for aria-describedby association.',- variant: 'Visual variant; attached overlaps input, detached floats below.',- },-};diff --git a/packages/core/src/Field/XDSField.tsx b/packages/core/src/Field/XDSField.tsxindex cb893ae1e0..fe9e222cb2 100644--- a/packages/core/src/Field/XDSField.tsx+++ b/packages/core/src/Field/XDSField.tsx@@ -20,7 +20,7 @@ import {type ReactNode, use} from 'react';import * as stylex from '@stylexjs/stylex';import type {XDSBaseProps} from '../XDSBaseProps';import {XDSFieldLabel} from './XDSFieldLabel';-import {XDSFieldStatus} from './XDSFieldStatus';+import {XDSFieldStatus} from '../FieldStatus/XDSFieldStatus';import {spacingVars, borderVars} from '../theme/tokens.stylex';import type {XDSIconType} from '../Icon';import {xdsClassName, mergeProps} from '../utils';diff --git a/packages/core/src/Field/index.ts b/packages/core/src/Field/index.tsindex 84c2838c16..1e03fbdd48 100644--- a/packages/core/src/Field/index.ts+++ b/packages/core/src/Field/index.ts@@ -19,12 +19,12 @@ export type {} from './XDSField';export {XDSFieldLabel} from './XDSFieldLabel';export type {XDSFieldLabelProps} from './XDSFieldLabel';-export {XDSFieldStatus} from './XDSFieldStatus';+export {XDSFieldStatus} from '../FieldStatus';export type {XDSFieldStatusProps,XDSFieldStatusVariant,XDSFieldStatusVariantMap,-} from './XDSFieldStatus';+} from '../FieldStatus';// Shared input typesexport type {XDSInputStatus, XDSInputStatusType, XDSInputSize} from './types';diff --git a/packages/core/src/FieldStatus/FieldStatus.doc.mjs b/packages/core/src/FieldStatus/FieldStatus.doc.mjsnew file mode 100644index 0000000000..af05cfdc20--- /dev/null+++ b/packages/core/src/FieldStatus/FieldStatus.doc.mjs@@ -0,0 +1,76 @@+// Copyright (c) Meta Platforms, Inc. and affiliates.++/** @type {import('../docs-types').ComponentDoc} */+export const docs = {+ name: 'FieldStatus',+ displayName: 'Field Status',+ group: 'Field',+ category: 'Data Input',+ isHiddenFromOverview: true,+ description:+ 'Status message component for form field validation feedback.',+ theming: {+ targets: [+ {className: 'xds-field-status', visualProps: ['type', 'variant']},+ ],+ },+ props: [+ {+ name: 'type',+ type: "'error' | 'warning' | 'success'",+ description: 'Status type.',+ required: true,+ },+ {+ name: 'message',+ type: 'string',+ description: 'Status message text.',+ required: true,+ },+ {+ name: 'id',+ type: 'string',+ description: 'ID for aria-describedby association.',+ },+ {+ name: 'variant',+ type: "'attached' | 'detached'",+ description:+ 'Visual variant: attached overlaps the input, detached floats below.',+ default: "'attached'",+ },+ ],+ usage: {+ description:+ 'FieldStatus renders validation feedback for fields and field-like controls. Use it directly for custom controls that need the same error, warning, or success presentation as XDSField.',+ bestPractices: [+ {+ guidance: true,+ description:+ 'Use attached status below bordered inputs when the message belongs to that input.',+ },+ {+ guidance: true,+ description:+ 'Use detached status for controls like checkboxes, switches, and custom controls where overlap would be visually awkward.',+ },+ {+ guidance: false,+ description:+ 'Use FieldStatus for general alerts or page-level notices; use Banner or Toast instead.',+ },+ ],+ },+};++/** @type {import('../docs-types').TranslationDoc} */+export const docsDense = {+ description:+ 'Validation feedback message for fields/custom controls. Supports error, warning, success and attached/detached variants.',+ propDescriptions: {+ type: 'error/warning/success status tone',+ message: 'visible validation feedback text',+ id: 'id for aria-describedby association',+ variant: 'attached overlaps input; detached floats below',+ },+};diff --git a/packages/core/src/Field/XDSFieldStatus.tsx b/packages/core/src/FieldStatus/XDSFieldStatus.tsxsimilarity index 86%rename from packages/core/src/Field/XDSFieldStatus.tsxrename to packages/core/src/FieldStatus/XDSFieldStatus.tsxindex 7fdbe6bb0b..b04a57db40 100644--- a/packages/core/src/Field/XDSFieldStatus.tsx+++ b/packages/core/src/FieldStatus/XDSFieldStatus.tsx@@ -4,12 +4,14 @@* @file XDSFieldStatus.tsx* @input Uses React, stylex, theme tokens* @output Exports XDSFieldStatus component, XDSFieldStatusProps- * @position Core implementation; consumed by index.ts, XDSField.tsx, XDSSwitch.tsx, XDSCheckboxInput.tsx+ * @position Core implementation; consumed by Field, Switch, CheckboxInput, and the FieldStatus entrypoint** SYNC: When modified, update these files to stay in sync:- * - /packages/core/src/Field/Field.doc.mjs (props table, features, implementation notes)- * - /packages/core/src/Field/index.ts (exports if types change)- * - /packages/cli/templates/blocks/components/Field/ (showcase blocks)+ * - /packages/core/src/FieldStatus/FieldStatus.doc.mjs (props table, features, implementation notes)+ * - /packages/core/src/Field/Field.doc.mjs (compat docs when public API changes)+ * - /packages/core/src/FieldStatus/index.ts (exports if types change)+ * - /packages/core/src/Field/index.ts (compat re-export if public API changes)+ * - /packages/cli/templates/blocks/components/FieldStatus/ (showcase blocks)*/'use client';@@ -25,7 +27,7 @@ import {typographyVars,typeScaleVars,} from '../theme/tokens.stylex';-import type {XDSInputStatusType} from './types';+import type {XDSInputStatusType} from '../Field/types';import {useEntryAnimation} from '../hooks/useEntryAnimation';const styles = stylex.create({@@ -71,7 +73,7 @@ const colorStyles = stylex.create({* Theme packages can add custom variants via TypeScript module augmentation:* @example* ```- * declare module '@xds/core/Field' {+ * declare module '@xds/core/FieldStatus' {* interface XDSFieldStatusVariantMap {* 'inline': true;* }diff --git a/packages/core/src/FieldStatus/index.ts b/packages/core/src/FieldStatus/index.tsnew file mode 100644index 0000000000..0e3db433bc--- /dev/null+++ b/packages/core/src/FieldStatus/index.ts@@ -0,0 +1,17 @@+// Copyright (c) Meta Platforms, Inc. and affiliates.++'use client';++/**+ * @file index.ts+ * @input XDSFieldStatus component source+ * @output Exports XDSFieldStatus and related types+ * @position Entry point for @xds/core/FieldStatus subpath export+ */++export {XDSFieldStatus} from './XDSFieldStatus';+export type {+ XDSFieldStatusProps,+ XDSFieldStatusVariant,+ XDSFieldStatusVariantMap,+} from './XDSFieldStatus';diff --git a/packages/core/src/Switch/XDSSwitch.tsx b/packages/core/src/Switch/XDSSwitch.tsxindex e5b932bc89..827e18f82f 100644--- a/packages/core/src/Switch/XDSSwitch.tsx+++ b/packages/core/src/Switch/XDSSwitch.tsx@@ -35,7 +35,7 @@ import {typeScaleVars,} from '../theme/tokens.stylex';import {XDSFieldLabel} from '../Field/XDSFieldLabel';-import {XDSFieldStatus} from '../Field/XDSFieldStatus';+import {XDSFieldStatus} from '../FieldStatus/XDSFieldStatus';import type {XDSIconType} from '../Icon';import type {XDSInputStatus} from '../Field/types';import {XDSSpinner} from '../Spinner';diff --git a/pnpm-lock.yaml b/pnpm-lock.yamlindex 574dd9092a..3bfd0f9ca5 100644--- a/pnpm-lock.yaml+++ b/pnpm-lock.yaml@@ -136,6 +136,9 @@ importers:'@xds/theme-y2k':specifier: '*'version: link:../../packages/themes/y2k+ fflate:+ specifier: ^0.8.2+ version: 0.8.3lucide-react:specifier: ^1.17.0version: 1.17.0([email protected])@@ -4567,6 +4570,9 @@ packages:picomatch:optional: true+ resolution: {integrity: sha512-tbZNuJrLwGUp3zshBtdy4W+ORxZuIh8a5ilyIEQDC5rY1f3U20JMry0Ll3WBzU58EZKsEuJFXhb5gwv8CsPvgA==}+resolution: {integrity: sha512-XXTUwCvisa5oacNGRP9SfNtYBNAMi+RPwBFmblZEF7N7swHYQS6/Zfk7SRwx4D5j3CH211YNRco1DEMNVfZCnQ==}engines: {node: '>=16.0.0'}@@ -9960,6 +9966,8 @@ snapshots:optionalDependencies:picomatch: 4.0.4+ [email protected]: {}+dependencies:flat-cache: 4.0.1