Skip to content

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.json
index 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.ts
new file mode 100644
index 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.tsx
index 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.ts
index 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.ts
new file mode 100644
index 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.mjs
index 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.tsx
index 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.json
index 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.tsx
index 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.mjs
deleted file mode 100644
index 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.tsx
index 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.ts
index 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 types
export type {XDSInputStatus, XDSInputStatusType, XDSInputSize} from './types';
diff --git a/packages/core/src/FieldStatus/FieldStatus.doc.mjs b/packages/core/src/FieldStatus/FieldStatus.doc.mjs
new file mode 100644
index 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.tsx
similarity index 86%
rename from packages/core/src/Field/XDSFieldStatus.tsx
rename to packages/core/src/FieldStatus/XDSFieldStatus.tsx
index 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.ts
new file mode 100644
index 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.tsx
index 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.yaml
index 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.3
lucide-react:
specifier: ^1.17.0
version: 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
+
dependencies:
flat-cache: 4.0.1