@astryxdesign/cli 0.2.0 → 0.3.0

package/docs/internationalization.doc.mjs

@@ -1,370 +0,0 @@
-// Copyright (c) Meta Platforms, Inc. and affiliates.
-
-/** @type {import('../../core/src/docs-types').ReferenceDoc} */
-
-export const docs = {
-  name: 'internationalization',
-  title: 'Internationalization',
-  category: 'guide',
-  description:
-    'Set the active locale for astryx components, load locale catalogs, coexist with your own i18n library, swap languages at runtime, and test translations with the pseudo locale.',
-
-  sections: [
-    {
-      title: 'Quick Start',
-      category: 'guide',
-      content: [
-        {
-          type: 'prose',
-          text: 'Internationalization ships with `@astryxdesign/core`. There is nothing to install. Wrap your app in `<InternationalizationProvider>` and set the active `locale`; astryx components pick up localized strings from that provider.',
-        },
-        {
-          type: 'code',
-          lang: 'tsx',
-          label: 'Wrap your app',
-          code: `import {InternationalizationProvider} from '@astryxdesign/core/i18n';
-
-function App() {
-  return (
-    <InternationalizationProvider locale="en">
-      <YourApp />
-    </InternationalizationProvider>
-  );
-}`,
-        },
-        {
-          type: 'prose',
-          text: 'The provider always has the built-in English catalog. Pass additional catalogs through `messages` when you enable another locale.',
-        },
-        {
-          type: 'code',
-          lang: 'tsx',
-          label: 'Load an astryx locale catalog',
-          code: `import {InternationalizationProvider} from '@astryxdesign/core/i18n';
-import fr from '@astryxdesign/core/locales/fr.json';
-
-<InternationalizationProvider locale="fr" messages={{fr}}>
-  <App />
-</InternationalizationProvider>;`,
-        },
-        {
-          type: 'prose',
-          text: 'Astryx ships English today, with first-party translations for other locales on the roadmap. Until a locale is available from `@astryxdesign/core/locales/*`, apps can pass a local catalog with the same shape. See `@astryxdesign/core/locales/en.json` for the current key inventory. Missing keys fall back through the locale chain to English (for example, `pt-BR` walks to `pt`, then to shipped `en`).',
-        },
-        {
-          type: 'prose',
-          text: 'Locale catalogs only affect astryx strings. Your app can continue using its own i18n system for product copy.',
-        },
-      ],
-    },
-    {
-      title: 'Runtime language swap',
-      category: 'guide',
-      content: [
-        {
-          type: 'prose',
-          text: 'Re-render `<InternationalizationProvider>` with a new `locale` prop and every astryx string updates live. No reload, no separate API call.',
-        },
-        {
-          type: 'code',
-          lang: 'tsx',
-          label: 'Toggle between locales',
-          code: `const [locale, setLocale] = useState<'en' | 'fr'>('en');
-
-<InternationalizationProvider locale={locale} messages={{fr}}>
-  <Button
-    label={locale === 'en' ? 'Français' : 'English'}
-    onClick={() => setLocale(l => (l === 'en' ? 'fr' : 'en'))}
-  />
-  <App />
-</InternationalizationProvider>;`,
-        },
-        {
-          type: 'prose',
-          text: "Persisting the user's choice (localStorage, cookie, URL segment, account setting) is up to the consumer. Astryx reads whatever `locale` you pass in.",
-        },
-      ],
-    },
-    {
-      title: 'Text direction (RTL)',
-      category: 'guide',
-      content: [
-        {
-          type: 'prose',
-          text: "Astryx tracks text direction (`'ltr'` or `'rtl'`) alongside the locale. By default the direction is derived from the `locale` you pass to `<InternationalizationProvider>` via [`Intl.Locale.getTextInfo()`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/Locale/getTextInfo), so RTL locales such as Arabic (`ar`), Hebrew (`he`), Farsi (`fa`), and Urdu (`ur`) resolve to `'rtl'` automatically.",
-        },
-        {
-          type: 'code',
-          lang: 'tsx',
-          label: 'Direction derived from locale',
-          code: `import {InternationalizationProvider} from '@astryxdesign/core/i18n';
-
-// direction resolves to 'rtl' automatically from the Arabic locale
-<InternationalizationProvider locale="ar">
-  <App />
-</InternationalizationProvider>;`,
-        },
-        {
-          type: 'prose',
-          text: 'Pass the optional `dir` prop to force a direction. This overrides the locale-derived default — useful for RTL layout testing under an English catalog, or to skip derivation when you already know the direction.',
-        },
-        {
-          type: 'code',
-          lang: 'tsx',
-          label: 'Explicit direction override',
-          code: `// force RTL layout while keeping English strings
-<InternationalizationProvider locale="en" dir="rtl">
-  <App />
-</InternationalizationProvider>;`,
-        },
-        {
-          type: 'prose',
-          text: "There's one more step: tell the browser about the direction too. Add a `dir` attribute to your page — usually on the `<html>` tag. This is what makes text align to the correct side, punctuation and mixed-language text flow correctly, and layouts mirror. The provider handles astryx components; the `dir` attribute handles everything else on the page.",
-        },
-        {
-          type: 'prose',
-          text: "Astryx doesn't set `dir` for you — you set it, alongside the same direction you pass to the provider. If your app is server-rendered (like Next.js), the `getLocaleDirection()` helper computes the direction from a locale so you can set it while the page renders:",
-        },
-        {
-          type: 'code',
-          lang: 'tsx',
-          label: 'Set <html dir> in a Next.js root layout',
-          code: `import {getLocaleDirection} from '@astryxdesign/core/i18n';
-
-export default function RootLayout({children, params}) {
-  const {locale} = params;
-  return (
-    <html lang={locale} dir={getLocaleDirection(locale)}>
-      <body>{children}</body>
-    </html>
-  );
-}`,
-        },
-        {
-          type: 'prose',
-          text: 'In a plain client app, set the same attribute on `<html>` whenever the locale changes. (`getLocaleDirection()` safely returns `\'ltr\'` for anything it doesn\'t recognize, so you can call it with any locale string.)',
-        },
-        {
-          type: 'prose',
-          text: 'To make just one part of a left-to-right page right-to-left — say an Arabic quote or a comment thread — wrap that part in its own `<InternationalizationProvider dir="rtl">` and add `dir="rtl"` to the element around it. (One current limitation: pop-up overlays like menus and dialogs opened from inside that region aren\'t mirrored yet; that\'s coming in later RTL work.)',
-        },
-      ],
-    },
-    {
-      title: "Overriding astryx's default text",
-      category: 'guide',
-      content: [
-        {
-          type: 'prose',
-          text: 'Use `overrides` to change individual strings without shipping a full catalog. Overrides are keyed by locale and merged on top of the built-in and user-supplied catalogs.',
-        },
-        {
-          type: 'code',
-          lang: 'tsx',
-          label: 'Change one string in English',
-          code: `<InternationalizationProvider
-  locale="en"
-  overrides={{en: {'@astryx.pagination.next': 'Next →'}}}
->
-  <App />
-</InternationalizationProvider>`,
-        },
-        {
-          type: 'prose',
-          text: 'Overrides win over both bundled English and any `messages` catalog for the same key. Use them for brand voice tweaks or one-off wording changes.',
-        },
-      ],
-    },
-    {
-      title: 'Using astryx with your own i18n library',
-      category: 'guide',
-      content: [
-        {
-          type: 'prose',
-          text: "Astryx components render astryx strings through astryx's provider. Consumer components render consumer strings through whatever i18n library you already use: react-intl, i18next, next-intl, LinguiJS, and so on. The two systems coexist and read from the same source of truth for the active locale.",
-        },
-        {
-          type: 'code',
-          lang: 'tsx',
-          label: 'Astryx + react-intl side by side',
-          code: `import {InternationalizationProvider} from '@astryxdesign/core/i18n';
-import {Selector} from '@astryxdesign/core/Selector';
-import {Button} from '@astryxdesign/core/Button';
-import {FormattedMessage, IntlProvider, useIntl} from 'react-intl';
-import astryxFr from './locales/astryx/fr.json'; // astryx's UI, in French
-import appFr from './locales/app/fr.json';       // your app strings, in French
-
-function Pricing() {
-  // Consumer strings — resolved by react-intl.
-  const intl = useIntl();
-
-  return (
-    <section>
-      <h1><FormattedMessage id="pricing.heading" /></h1>
-
-      {/* Astryx Selector — trigger placeholder, search-box placeholder,
-          clear-button aria-label all resolved by
-          <InternationalizationProvider>. Options come from react-intl. */}
-      <Selector
-        label={intl.formatMessage({id: 'pricing.region.label'})}
-        options={[
-          {value: 'na', label: intl.formatMessage({id: 'pricing.region.na'})},
-          {value: 'eu', label: intl.formatMessage({id: 'pricing.region.eu'})},
-        ]}
-        hasSearch
-        hasClear
-      />
-
-      <Button label={intl.formatMessage({id: 'pricing.cta.subscribe'})} />
-    </section>
-  );
-}
-
-export default function App() {
-  return (
-    // Same locale, two providers reading their own catalogs.
-    <IntlProvider locale="fr" messages={appFr}>
-      <InternationalizationProvider locale="fr" messages={{fr: astryxFr}}>
-        <Pricing />
-      </InternationalizationProvider>
-    </IntlProvider>
-  );
-}`,
-        },
-        {
-          type: 'prose',
-          text: 'Keep the two providers in sync on locale, and each library owns its own catalog. Astryx never sees your app strings, and your i18n library never sees astryx internals. Runtime locale swap works the same way: re-render both providers with a new `locale` prop and the whole tree updates live.',
-        },
-        {
-          type: 'prose',
-          text: "Single-catalog usage (where an external i18n runtime like react-intl or i18next resolves both your app strings AND astryx's strings through one provider) is on the roadmap via a `Translator` adapter. Track [facebook/astryx#4029](https://github.com/facebook/astryx/issues/4029). For now, run the two providers side by side as shown above.",
-        },
-      ],
-    },
-    {
-      title: 'Using astryx as your i18n library',
-      category: 'guide',
-      content: [
-        {
-          type: 'prose',
-          text: "For production apps with substantial localization needs, we recommend a dedicated i18n library such as react-intl, i18next, next-intl, or LinguiJS. If your app is small or you do not want another runtime, you can resolve your own strings through astryx too. Keep app keys in a separate namespace from `@astryx.*`, and include your own `en` catalog because astryx's built-in English fallback only contains astryx component strings.",
-        },
-        {
-          type: 'code',
-          lang: 'tsx',
-          label: 'Translate app strings with astryx',
-          code: `import {Button} from '@astryxdesign/core/Button';
-import {
-  InternationalizationProvider,
-  useTranslator,
-  type Catalog,
-  type MessagesByLocale,
-} from '@astryxdesign/core/i18n';
-
-const en: Catalog = {
-  '@myapp.actions.save': {defaultMessage: 'Save'},
-};
-
-const fr: Catalog = {
-  '@myapp.actions.save': {defaultMessage: 'Enregistrer'},
-};
-
-const messages: MessagesByLocale = {en, fr};
-
-function SaveButton() {
-  const t = useTranslator();
-  return <Button label={t('@myapp.actions.save')} />;
-}
-
-export default function App() {
-  return (
-    <InternationalizationProvider locale="fr" messages={messages}>
-      <SaveButton />
-    </InternationalizationProvider>
-  );
-}`,
-        },
-        {
-          type: 'prose',
-          text: '`Catalog` types a single locale file; `MessagesByLocale` types the map passed to `messages`. A catalog entry uses the same `{defaultMessage, description?}` shape as `@astryxdesign/core/locales/en.json`.',
-        },
-      ],
-    },
-    {
-      title: 'Testing your translations',
-      category: 'guide',
-      content: [
-        {
-          type: 'prose',
-          text: 'Astryx generates a `pseudo` locale that wraps every string in `⟦…⟧` and replaces letters with accented look-alikes. Switch to it in development to catch hardcoded astryx strings and layout issues caused by longer text.',
-        },
-        {
-          type: 'code',
-          lang: 'tsx',
-          label: 'Turn on pseudo-localization',
-          code: `import {InternationalizationProvider} from '@astryxdesign/core/i18n';
-import pseudo from '@astryxdesign/core/locales/pseudo.json';
-
-<InternationalizationProvider locale="pseudo" messages={{pseudo}}>
-  <App />
-</InternationalizationProvider>;`,
-        },
-      ],
-    },
-    {
-      title: 'For contributors',
-      category: 'guide',
-      content: [
-        {
-          type: 'heading',
-          level: 3,
-          text: 'Developers',
-        },
-        {
-          type: 'prose',
-          text: 'Astryx component authors read strings with `useTranslator()` rather than hardcoding user-facing text.',
-        },
-        {
-          type: 'code',
-          lang: 'tsx',
-          label: 'Read an astryx string',
-          code: `import {useTranslator} from '@astryxdesign/core/i18n';
-
-function SaveButton() {
-  const t = useTranslator();
-  return <button>{t('@astryx.actions.save')}</button>;
-}`,
-        },
-        {
-          type: 'prose',
-          text: "Astryx's own strings live in `packages/core/locales/en.json`. New user-facing strings must go through `useTranslator`; this is enforced by the `@astryx/no-hardcoded-i18n-string` ESLint rule. See the AI contribution guide for the alias-and-resolve pattern used when adding new keys.",
-        },
-        {
-          type: 'prose',
-          text: "Component authors read the ambient text direction with `useDirection()`. Reach for it only when CSS logical properties can't express the mirroring — swapping a directional icon, mirroring behavioral logic (slider math, keyboard nav), or direction-specific geometry. It returns `'ltr'` when called outside a provider, matching the silent-fallback behavior of `useTranslator`.",
-        },
-        {
-          type: 'code',
-          lang: 'tsx',
-          label: 'useDirection() in a component',
-          code: `import {useDirection} from '@astryxdesign/core/i18n';
-
-function NextButton() {
-  const direction = useDirection();
-  const icon = direction === 'rtl' ? 'chevronLeft' : 'chevronRight';
-  return <Icon icon={icon} />;
-}`,
-        },
-        {
-          type: 'heading',
-          level: 3,
-          text: 'Translators',
-        },
-        {
-          type: 'prose',
-          text: 'Crowdin is the preferred way to contribute — [join a language](https://crowdin.com/project/astryx), translate strings in the web UI, and your work syncs back to the repo without opening a PR. Direct PRs against `packages/core/locales/*.json` also work if you prefer that flow.',
-        },
-      ],
-    },
-  ],
-};

package/docs/layout.doc.dense.mjs

@@ -1,95 +0,0 @@
-// Copyright (c) Meta Platforms, Inc. and affiliates.
-
-/** @type {import('../../core/src/docs-types').ReferenceTranslationDoc} */
-
-export const docsDense = {
-  description:
-    'frame-first app layout: shell choice, region budgets, cards vs rows',
-  sections: [
-    {
-      section: 'Frame First',
-      title: 'Frame First',
-      content: [
-        {
-          type: 'prose',
-          text: 'decide frame before content. content-first (Card-wrapped sections in a scroll column) = prototype look.',
-        },
-        {
-          type: 'list',
-          items: [
-            'pick frame: AppShell (nav apps) | Layout+LayoutPanel+LayoutContent (multi-pane tools) | plain column (docs/forms)',
-            'budget regions in px first: side nav 240-280, rail 64-72, inspector 340-420, facet rail 220-260',
-            'container policy per region: dense data = rows; dashboards/galleries = card grids',
-            'write responsive contract up front',
-          ],
-        },
-        null,
-      ],
-    },
-    {
-      section: 'App Archetypes',
-      title: 'App Archetypes',
-      content: [
-        {
-          type: 'prose',
-          text: 'container choice tracks archetype, not preference.',
-        },
-        null,
-        {
-          type: 'prose',
-          text: 'start from matching template (astryx template --list), study with --skeleton.',
-        },
-      ],
-    },
-    {
-      section: 'Cards vs Rows',
-      title: 'Cards vs Rows',
-      content: [
-        {
-          type: 'prose',
-          text: 'Card = widget container, NOT list-item wrapper. dense/scannable/selectable data = rows: Table (columnar) or List/Item (single-line), edge-to-edge, 32-40px rows, dividers.',
-        },
-        {
-          type: 'list',
-          items: [
-            'Table+plugins: hosts, deployments, monitors, users',
-            'List/Item rows: issues, files, conversations',
-            'Card: KPI tiles, chart panels, gallery entries, settings groups',
-            'EmptyState for zero-match',
-          ],
-        },
-        {
-          type: 'list',
-          items: [
-            'no Card-wrapped list items (card soup)',
-            'no stacked full-width Cards as page structure',
-            'no Cards in Cards',
-            'no decorative Badge — counts/enums only; StatusDot/Token for status',
-          ],
-        },
-      ],
-    },
-    {
-      section: 'Panels and Inspectors',
-      title: 'Panels and Inspectors',
-      content: [
-        {
-          type: 'prose',
-          text: 'master-detail: row select opens fixed-width inspector (LayoutPanel end slot + width budget + resizable/useResizable). overlay content <=1024px, do not compress.',
-        },
-        null,
-      ],
-    },
-    {
-      section: 'Responsive Contract',
-      title: 'Responsive Contract',
-      content: [
-        {
-          type: 'prose',
-          text: 'declare breakpoint behavior as comment at frame root: which regions collapse/overlay/drop at which widths.',
-        },
-        null,
-      ],
-    },
-  ],
-};

package/docs/layout.doc.mjs

@@ -1,160 +0,0 @@
-// Copyright (c) Meta Platforms, Inc. and affiliates.
-
-/** @type {import('../../core/src/docs-types').ReferenceDoc} */
-
-export const docs = {
-  name: 'layout',
-  title: 'Layout',
-  category: 'guide',
-  description:
-    'Frame-first app layout: choosing a shell, budgeting regions, and when to use cards vs rows.',
-
-  sections: [
-    {
-      title: 'Frame First',
-      content: [
-        {
-          type: 'prose',
-          text: 'Decide the frame before writing any content. Real applications are built top-down: pick the shell, name its regions, give each region an explicit size budget, then fill regions with content. Content-first layout (writing sections and wrapping each one in a Card) produces a padded scroll column that reads as a prototype, not a product.',
-        },
-        {
-          type: 'list',
-          style: 'ordered',
-          items: [
-            'Pick the frame: AppShell (top nav and/or side nav apps), Layout + LayoutPanel + LayoutContent (multi-pane tools like explorers and consoles), or a plain content column (documents, marketing, forms)',
-            'Budget regions in px before filling them: side nav 240–280, icon rail 64–72, detail/inspector panel 340–420, filter/facet rail 220–260',
-            'Decide the container policy per region: dense data renders as rows; widget dashboards and galleries render as card grids (see Cards vs Rows)',
-            'Write the responsive contract up front: which regions collapse, overlay, or drop at which breakpoints (see Responsive Contract)',
-          ],
-        },
-        {
-          type: 'code',
-          lang: 'tsx',
-          label: 'A three-region tool frame',
-          code: `// Frame: nav 256 | content flex | inspector 380 (resizable)
-<AppShell sideNav={<SideNav>{/* nav items */}</SideNav>} contentPadding={0}>
-  <Layout>
-    <LayoutContent>{/* dense list or table, edge-to-edge */}</LayoutContent>
-    <LayoutPanel width={380} resizable={{minSizePx: 320, maxSizePx: 480}} hasDivider>
-      {/* inspector for the selected row */}
-    </LayoutPanel>
-  </Layout>
-</AppShell>`,
-        },
-      ],
-    },
-    {
-      title: 'App Archetypes',
-      content: [
-        {
-          type: 'prose',
-          text: 'Match the frame and container policy to the kind of app you are building. These recipes are distilled from product-scale apps built with the design system; container choice tracks the archetype, not personal preference.',
-        },
-        {
-          type: 'table',
-          headers: ['Archetype', 'Frame', 'Container policy'],
-          rows: [
-            [
-              'Tracker / work tool (issues, tickets, CRM)',
-              'AppShell + SideNav; inspector LayoutPanel on select',
-              'Rows only. Grouped edge-to-edge lists, zero cards',
-            ],
-            [
-              'Console / observability (metrics, logs, deploys)',
-              'AppShell + SideNav or TopNav + TabList',
-              'Card grid for dashboard widgets; Table for everything else',
-            ],
-            [
-              'Messaging / feed',
-              'Column frame: rail + sidebar + stream + panel',
-              'Rows and bubbles. No cards in the stream',
-            ],
-            [
-              'Media library / gallery',
-              'AppShell + TopNav; grid content',
-              'Card grid (ClickableCard) with dense metadata rows in detail views',
-            ],
-            [
-              'Settings / forms',
-              'AppShell + SideNav or settings template',
-              'Sections with FormLayout; Card only to group dangerous or billing actions',
-            ],
-          ],
-        },
-        {
-          type: 'prose',
-          text: 'Start from a template that matches the archetype (`npx astryx template --list`), then study its structure with `--skeleton` before customizing.',
-        },
-      ],
-    },
-    {
-      title: 'Cards vs Rows',
-      content: [
-        {
-          type: 'prose',
-          text: 'Card is a widget container, not a list-item wrapper. The fastest way to make an app look like a generic AI prototype is to wrap every record in a Card with a Badge. Dense data (anything the user scans, filters, or selects) belongs in rows: Table for columnar data, List/Item for single-line records, edge-to-edge with dividers and 32–40px row height.',
-        },
-        {
-          type: 'list',
-          style: 'do',
-          items: [
-            'Table (with selection/sorting plugins) for columnar records: hosts, deployments, monitors, users',
-            'List/Item rows for scannable single-line records: issues, files, conversations',
-            'Card for self-contained widgets: KPI tiles, chart panels, gallery entries, settings groups',
-            'EmptyState inside the region when a filter matches nothing',
-          ],
-        },
-        {
-          type: 'list',
-          style: 'dont',
-          items: [
-            'Wrapping each list item in a Card (card soup)',
-            'Stacking full-width Cards as a substitute for page structure',
-            'Nesting Cards inside Cards',
-            'Using Badge as decoration: reserve it for counts and enumerated states; use StatusDot or Token for status and metadata',
-          ],
-        },
-      ],
-    },
-    {
-      title: 'Panels and Inspectors',
-      content: [
-        {
-          type: 'prose',
-          text: 'Master-detail is the backbone of tool UIs: selecting a row opens a fixed-width inspector panel rather than navigating away. Use LayoutPanel in the end slot with an explicit width budget; add resizable (useResizable) for user control, and let the panel overlay the content region below ~1024px instead of compressing it.',
-        },
-        {
-          type: 'code',
-          lang: 'tsx',
-          label: 'Inspector that overlays at narrow widths',
-          code: `<LayoutPanel
-  width={380}
-  hasDivider
-  isScrollable
-  label="Details"
-  resizable={{minSizePx: 320, maxSizePx: 480, autoSaveId: 'inspector'}}>
-  {selected ? <DetailFields item={selected} /> : <EmptyState title="Nothing selected" />}
-</LayoutPanel>`,
-        },
-      ],
-    },
-    {
-      title: 'Responsive Contract',
-      content: [
-        {
-          type: 'prose',
-          text: 'Declare breakpoint behavior as a contract before building, and keep it in a comment at the frame root. A typical contract: full frame above 1024px; inspector panels overlay the content column at 1024px and below; the side nav collapses into MobileNav at 768px and below. Deciding this up front keeps every region change intentional instead of emergent.',
-        },
-        {
-          type: 'code',
-          lang: 'tsx',
-          label: 'Contract comment at the frame root',
-          code: `// Responsive contract:
-//   > 1024px  nav 256 | content | inspector 380
-//   <= 1024px inspector overlays content (position: absolute, end-aligned)
-//   <= 768px  nav collapses into MobileNav drawer; toolbar actions wrap`,
-        },
-      ],
-    },
-  ],
-};