@astryxdesign/core 0.2.0 → 0.3.0-canary.041a0ef

package/dist/theme/useTheme.js

@@ -5,23 +5,25 @@
 /**
  * @file useTheme.ts
  * @input ThemeContext provided by Theme
- * @output Exports useTheme hook for programmatic access to resolved theme tokens
+ * @output Exports useTheme and useThemeName hooks for programmatic theme access
  * @position Theme hook; used by data viz, canvas, and non-CSS consumers
  *
  * Provides synchronous access to theme token values resolved for the
  * current color mode — no DOM reads on the provider path, no double render.
- * Without a reachable ThemeContext it consults `<html data-theme>` (kept in
- * sync by Theme) via a single shared, refcounted MutationObserver before
- * assuming OS preference; provider-path consumers subscribe to a no-op
- * store instead (the same args-switch technique useMediaQuery uses), so
- * mounting under a Theme never creates an observer. Token resolution is
- * shared with the server-safe helpers in ./tokens.ts.
+ * Without a reachable ThemeContext it consults `<html data-theme>` and
+ * `<html data-astryx-theme>` (kept in sync by Theme) via shared, refcounted
+ * MutationObservers before assuming OS preference/default tokens. Provider-path
+ * consumers subscribe to no-op stores instead, so mounting under a Theme never
+ * creates an observer. Token resolution is shared with the server-safe helpers
+ * in ./tokens.ts.
  *
  * SYNC: When modified, update:
  * - /packages/core/src/theme/index.ts
  */
 import { createContext, use, useMemo, useSyncExternalStore } from 'react';
 import { resolveThemeTokens } from "./tokens.js";
+import { getRegisteredTheme } from "./themeRegistry.js";
+import { dataAttr } from "../naming.js";
 import { useMediaQuery } from "../hooks/useMediaQuery.js";
 
 // =============================================================================
@@ -53,44 +55,77 @@ ThemeContext.displayName = 'ThemeContext';
 // Hook
 // =============================================================================
 
-function getRootThemeAttrSnapshot() {
+function getRootModeAttrSnapshot() {
   if (typeof document === 'undefined') {
     return null;
   }
   const attr = document.documentElement.getAttribute('data-theme');
   return attr === 'light' || attr === 'dark' ? attr : null;
 }
-function getRootThemeAttrServerSnapshot() {
+function getRootModeAttrServerSnapshot() {
   return null;
 }
-function getNullThemeMode() {
+function getRootNameAttrSnapshot() {
+  if (typeof document === 'undefined') {
+    return null;
+  }
+  return document.documentElement.getAttribute(dataAttr('theme'));
+}
+function getRootNameAttrServerSnapshot() {
+  return null;
+}
+function getNullThemeSnapshot() {
   return null;
 }
 
 // Every no-context consumer wants the same <html data-theme> attribute, so
 // one MutationObserver — refcounted via this listener set — serves all of
 // them instead of one per consumer.
-const rootThemeAttrListeners = new Set();
-let rootThemeAttrObserver = null;
-function notifyRootThemeAttrListeners() {
-  for (const listener of rootThemeAttrListeners) {
+const rootModeAttrListeners = new Set();
+let rootModeAttrObserver = null;
+const rootNameAttrListeners = new Set();
+let rootNameAttrObserver = null;
+function notifyRootModeAttrListeners() {
+  for (const listener of rootModeAttrListeners) {
     listener();
   }
 }
-function subscribeRootThemeAttr(onStoreChange) {
-  rootThemeAttrListeners.add(onStoreChange);
-  if (rootThemeAttrListeners.size === 1 && typeof MutationObserver !== 'undefined') {
-    rootThemeAttrObserver = new MutationObserver(notifyRootThemeAttrListeners);
-    rootThemeAttrObserver.observe(document.documentElement, {
+function subscribeRootModeAttr(onStoreChange) {
+  rootModeAttrListeners.add(onStoreChange);
+  if (rootModeAttrListeners.size === 1 && typeof MutationObserver !== 'undefined') {
+    rootModeAttrObserver = new MutationObserver(notifyRootModeAttrListeners);
+    rootModeAttrObserver.observe(document.documentElement, {
       attributes: true,
       attributeFilter: ['data-theme']
     });
   }
   return () => {
-    rootThemeAttrListeners.delete(onStoreChange);
-    if (rootThemeAttrListeners.size === 0 && rootThemeAttrObserver) {
-      rootThemeAttrObserver.disconnect();
-      rootThemeAttrObserver = null;
+    rootModeAttrListeners.delete(onStoreChange);
+    if (rootModeAttrListeners.size === 0 && rootModeAttrObserver) {
+      rootModeAttrObserver.disconnect();
+      rootModeAttrObserver = null;
+    }
+  };
+}
+function notifyRootNameAttrListeners() {
+  for (const listener of rootNameAttrListeners) {
+    listener();
+  }
+}
+function subscribeRootNameAttr(onStoreChange) {
+  rootNameAttrListeners.add(onStoreChange);
+  if (rootNameAttrListeners.size === 1 && typeof MutationObserver !== 'undefined') {
+    rootNameAttrObserver = new MutationObserver(notifyRootNameAttrListeners);
+    rootNameAttrObserver.observe(document.documentElement, {
+      attributes: true,
+      attributeFilter: [dataAttr('theme')]
+    });
+  }
+  return () => {
+    rootNameAttrListeners.delete(onStoreChange);
+    if (rootNameAttrListeners.size === 0 && rootNameAttrObserver) {
+      rootNameAttrObserver.disconnect();
+      rootNameAttrObserver = null;
     }
   };
 }
@@ -105,8 +140,26 @@ function subscribeNoop() {
  * a no-op store when a ThemeContext exists — instead of skipping the hook
  * call, so provider-path consumers never touch the DOM or the observer.
  */
-function useRootThemeModeAttr(hasCtx) {
-  return useSyncExternalStore(hasCtx ? subscribeNoop : subscribeRootThemeAttr, hasCtx ? getNullThemeMode : getRootThemeAttrSnapshot, getRootThemeAttrServerSnapshot);
+function useRootModeAttr(hasCtx) {
+  return useSyncExternalStore(hasCtx ? subscribeNoop : subscribeRootModeAttr, hasCtx ? getNullThemeSnapshot : getRootModeAttrSnapshot, getRootModeAttrServerSnapshot);
+}
+function useRootThemeNameAttr(hasCtx) {
+  return useSyncExternalStore(hasCtx ? subscribeNoop : subscribeRootNameAttr, hasCtx ? getNullThemeSnapshot : getRootNameAttrSnapshot, getRootNameAttrServerSnapshot);
+}
+
+/**
+ * Return the nearest active Astryx theme name.
+ *
+ * Uses ThemeContext when present and otherwise follows the root Theme's
+ * <html data-astryx-theme> attribute. This is intentionally lighter than
+ * useTheme() for consumers that only need theme identity, such as semantic
+ * icon resolution.
+ */
+export function useThemeName() {
+  const ctx = use(ThemeContext);
+  const hasCtx = ctx != null;
+  const rootThemeName = useRootThemeNameAttr(hasCtx);
+  return ctx?.theme.name ?? rootThemeName;
 }
 
 /**
@@ -140,12 +193,14 @@ export function useTheme() {
   // Falls back to the root Theme's mode via <html data-theme> when there's
   // no ThemeContext ancestor (e.g. useToast's detached fallback viewport).
   // Resolves to null when `ctx` is present, so it has no effect there.
-  const rootAttrMode = useRootThemeModeAttr(ctx != null);
+  const hasCtx = ctx != null;
+  const rootAttrMode = useRootModeAttr(hasCtx);
+  const rootThemeName = useRootThemeNameAttr(hasCtx);
 
   // Resolve 'system' to 'light' | 'dark' using the OS preference
   const prefersDark = useMediaQuery('(prefers-color-scheme: dark)');
   const mode = ctx?.mode ?? rootAttrMode ?? 'system';
-  const theme = ctx?.theme ?? null;
+  const theme = ctx?.theme ?? getRegisteredTheme(rootThemeName);
   const effectiveMode = mode === 'system' ? prefersDark ? 'dark' : 'light' : mode;
 
   // Build the full resolved map, memoized on theme + effective mode

package/dist/utils/focusOutline.stylex.d.ts

@@ -0,0 +1,74 @@
+/**
+ * @file focusOutline.stylex.ts
+ * @input Uses StyleX and theme color tokens
+ * @output Exports shared focus-outline prop builders
+ * @position Internal utility for consistent keyboard focus outlines across core components
+ *
+ * Centralizes the standard Astryx focus outline, shown only for keyboard focus.
+ * Every focusable surface drew the same 2px accent ring at 2px offset already;
+ * writing it per component meant five identical definitions to keep in step.
+ *
+ * These are utility styles, deliberately NOT a theme target. A shared
+ * `astryx-focus-outline` class was tried and pulled: a theme can only override
+ * the ring unconditionally through it (`generateThemeRules` mangles
+ * `:focus-visible` into `.focus-visible` and truncates `:has(:focus-visible)`
+ * at the paren), so the one thing such a target exists for — restyling a
+ * STATE — is exactly what it cannot express. Making focus outlines themeable
+ * is worth doing on top of this consolidation, once that is fixed.
+ */
+import * as stylex from '@stylexjs/stylex';
+export declare const focusOutlineStyles: Readonly<{
+    readonly focusVisible: Readonly<{
+        readonly outlineWidth: stylex.StyleXClassNameFor<"outlineWidth", "0" | "2px">;
+        readonly outlineStyle: stylex.StyleXClassNameFor<"outlineStyle", "none" | "solid">;
+        readonly outlineColor: stylex.StyleXClassNameFor<"outlineColor", "light-dark(#0064E0, #2694FE)" | null>;
+        readonly outlineOffset: stylex.StyleXClassNameFor<"outlineOffset", "0" | "3px">;
+    }>;
+    readonly focusWithin: Readonly<{
+        readonly outlineWidth: stylex.StyleXClassNameFor<"outlineWidth", "0" | "2px">;
+        readonly outlineStyle: stylex.StyleXClassNameFor<"outlineStyle", "none" | "solid">;
+        readonly outlineColor: stylex.StyleXClassNameFor<"outlineColor", "light-dark(#0064E0, #2694FE)" | null>;
+        readonly outlineOffset: stylex.StyleXClassNameFor<"outlineOffset", "0" | "3px">;
+    }>;
+    readonly publishFocusVisibleVars: Readonly<{
+        readonly '--_focus-outline': stylex.StyleXClassNameFor<"--_focus-outline", "none" | `2px solid ${stylex.StyleXVar<"light-dark(#0064E0, #2694FE)">}`>;
+        readonly '--_focus-outline-offset': stylex.StyleXClassNameFor<"--_focus-outline-offset", "0" | "3px">;
+    }>;
+    readonly focusWithinOrPublished: Readonly<{
+        readonly outline: stylex.StyleXClassNameFor<"outline", `2px solid ${stylex.StyleXVar<"light-dark(#0064E0, #2694FE)">}` | "var(--_focus-outline, none)">;
+        readonly outlineOffset: stylex.StyleXClassNameFor<"outlineOffset", "3px" | "var(--_focus-outline-offset, 0)">;
+    }>;
+}>;
+type StyleXPropsArg = unknown;
+export declare const focusOutlineProps: {
+    readonly focusVisible: (...styles: StyleXPropsArg[]) => Readonly<{
+        className?: string;
+        'data-style-src'?: string;
+        style?: Readonly<{
+            [$$Key$$: string]: string | number;
+        }>;
+    }>;
+    readonly focusWithin: (...styles: StyleXPropsArg[]) => Readonly<{
+        className?: string;
+        'data-style-src'?: string;
+        style?: Readonly<{
+            [$$Key$$: string]: string | number;
+        }>;
+    }>;
+    readonly publishFocusVisibleVars: (...styles: StyleXPropsArg[]) => Readonly<{
+        className?: string;
+        'data-style-src'?: string;
+        style?: Readonly<{
+            [$$Key$$: string]: string | number;
+        }>;
+    }>;
+    readonly focusWithinOrPublished: (...styles: StyleXPropsArg[]) => Readonly<{
+        className?: string;
+        'data-style-src'?: string;
+        style?: Readonly<{
+            [$$Key$$: string]: string | number;
+        }>;
+    }>;
+};
+export {};
+//# sourceMappingURL=focusOutline.stylex.d.ts.map

package/dist/utils/focusOutline.stylex.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"focusOutline.stylex.d.ts","sourceRoot":"","sources":["../../src/utils/focusOutline.stylex.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,KAAK,MAAM,MAAM,kBAAkB,CAAC;AAyB3C,eAAO,MAAM,kBAAkB;;;;;;;;;;;;;;;;;;;;;EAmD7B,CAAC;AAIH,KAAK,cAAc,GAAG,OAAO,CAAC;AAiB9B,eAAO,MAAM,iBAAiB;uCAdT,cAAc,EAAE;;;;;;;sCAAhB,cAAc,EAAE;;;;;;;kDAAhB,cAAc,EAAE;;;;;;;iDAAhB,cAAc,EAAE;;;;;;;CAuB3B,CAAC"}

package/dist/utils/focusOutline.stylex.js

@@ -0,0 +1,95 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file focusOutline.stylex.ts
+ * @input Uses StyleX and theme color tokens
+ * @output Exports shared focus-outline prop builders
+ * @position Internal utility for consistent keyboard focus outlines across core components
+ *
+ * Centralizes the standard Astryx focus outline, shown only for keyboard focus.
+ * Every focusable surface drew the same 2px accent ring at 2px offset already;
+ * writing it per component meant five identical definitions to keep in step.
+ *
+ * These are utility styles, deliberately NOT a theme target. A shared
+ * `astryx-focus-outline` class was tried and pulled: a theme can only override
+ * the ring unconditionally through it (`generateThemeRules` mangles
+ * `:focus-visible` into `.focus-visible` and truncates `:has(:focus-visible)`
+ * at the paren), so the one thing such a target exists for — restyling a
+ * STATE — is exactly what it cannot express. Making focus outlines themeable
+ * is worth doing on top of this consolidation, once that is fixed.
+ */
+
+import * as stylex from '@stylexjs/stylex';
+import "../theme/tokens.stylex.js";
+import { colorVars } from "../theme/tokens.stylex.js";
+const FOCUS_OUTLINE_WIDTH = '2px';
+// 3px, per Design Conventions §User Interaction States: "2px --color-accent
+// outline at 3px offset". Most components had drifted to 2px; Button, Calendar,
+// Dialog and Pagination were the ones matching the spec, so the consolidation
+// takes their value rather than the majority's.
+const FOCUS_OUTLINE_OFFSET = '3px';
+const FOCUS_OUTLINE_COLOR = colorVars['--color-accent'];
+
+/**
+ * Written as longhands rather than the `outline` shorthand.
+ *
+ * A shorthand resets every longhand it covers, so `outline: 2px solid accent`
+ * would clobber a later `outlineColor` no matter the order — which is how
+ * destructive buttons silently lost their red ring. With longhands, a variant
+ * can re-color the ring and inherit width, style and offset.
+ */
+const focusOutlineLonghands = {
+  outlineWidth: FOCUS_OUTLINE_WIDTH,
+  outlineStyle: 'solid',
+  outlineColor: FOCUS_OUTLINE_COLOR
+};
+export const focusOutlineStyles = {
+  focusVisible: {
+    kMeerF: "x1k57tk5 x784prv",
+    k3XXqK: "x1t137rt x9v5kkp",
+    kjBf7l: "xzunyri",
+    kInvED: "x1wfwxd8 xj3ae5l",
+    $$css: true
+  },
+  focusWithin: {
+    kMeerF: "x1k57tk5 x1odlxkb",
+    k3XXqK: "x1t137rt xnnj0qo",
+    kjBf7l: "xee0hk0",
+    kInvED: "x1wfwxd8 xscfbxq",
+    $$css: true
+  },
+  publishFocusVisibleVars: {
+    "--_focus-outline": "x17wzz1v x1bqhfga",
+    "--_focus-outline-offset": "xgzxwq1 x1tcr69y",
+    $$css: true
+  },
+  focusWithinOrPublished: {
+    kI3sdo: "xaw4jrz x1irc7jg",
+    kInvED: "x1kvmbwa xscfbxq",
+    $$css: true
+  }
+};
+
+// StyleX does not expose a stable public input type for stylex.props();
+// keep this helper permissive so it mirrors stylex.props() itself.
+
+function makeFocusOutlineProps(style) {
+  return (...styles) =>
+  // Caller styles LAST, so a component can deliberately re-color its ring —
+  // destructive buttons ring in error red, not accent. StyleX is last-wins,
+  // and reversing this to protect the ring silently ate that override.
+  //
+  // The hazard in this direction is the opposite one: a caller whose base
+  // style carries `outline: 'none'` wipes the ring out entirely (TreeList
+  // did, and shipped a focusable row with no visible focus). Two things
+  // guard it — this file states the rule, and the ring is written as
+  // LONGHANDS, so an override has to name `outlineStyle`/`outlineWidth`
+  // explicitly rather than erasing them through the `outline` shorthand.
+  stylex.props(style, ...styles);
+}
+export const focusOutlineProps = {
+  focusVisible: makeFocusOutlineProps(focusOutlineStyles.focusVisible),
+  focusWithin: makeFocusOutlineProps(focusOutlineStyles.focusWithin),
+  publishFocusVisibleVars: makeFocusOutlineProps(focusOutlineStyles.publishFocusVisibleVars),
+  focusWithinOrPublished: makeFocusOutlineProps(focusOutlineStyles.focusWithinOrPublished)
+};

package/dist/utils/rtlStyles.d.ts

@@ -2,8 +2,8 @@
  * @file rtlStyles.ts
  * @input None
  * @output Shared StyleX style that horizontally mirrors an element under RTL
- * @position Core utility; applied to directional-icon wrappers in Calendar,
- *   Lightbox, and the Table expand/disclosure plugins
+ * @position Core utility; applied to directional icons in Calendar, Lightbox,
+ *   Pagination, Carousel and the Table expand/disclosure plugins
  *
  * `mirror` flips its element on the horizontal axis only when an ancestor
  * carries `dir="rtl"`. Using `scaleX(-1)` (not `scale(-1, -1)`) keeps the
@@ -12,6 +12,23 @@
  * down when expanded under RTL. The `:is([dir="rtl"] *)` selector matches the
  * MobileNav drawer convention; a bare `direction: rtl` alone won't trigger it.
  *
+ * `centerInline(blockOffset?)` horizontally centers an absolutely-positioned,
+ * auto-width element on the inline axis, correctly in BOTH LTR and RTL, with an
+ * optional block-axis (Y) offset composed into the same transform. It
+ * intentionally uses PHYSICAL `left: 50%` + `translateX(-50%)`: both reference
+ * the same physical edge, so the pair is direction-symmetric and centers
+ * identically regardless of `dir`. A logical `insetInlineStart: 50%` would flip
+ * the anchor edge in RTL while the physical translate does not, leaving the
+ * element off-center by its own width (centered in LTR, broken in RTL). This is
+ * the one case where physical `left` is the correct choice, so the
+ * `no-physical-properties` suppression lives here ONCE rather than at each call
+ * site. The `@astryx/no-physical-properties` lint recognises this exact pattern
+ * and points offenders here.
+ *
+ * `blockOffset` is any CSS length/percentage for translateY (pass `'0px'` for
+ * none): e.g. `centerInline('100%')` sits the element one full height below its
+ * anchor, `centerInline('-50%')` centers it on both axes.
+ *
  * SYNC: When modified, update:
  * - /packages/core/src/utils/index.ts
  */
@@ -20,5 +37,9 @@ export declare const rtlStyles: Readonly<{
     readonly mirror: Readonly<{
         readonly transform: stylex.StyleXClassNameFor<"transform", "scaleX(-1)" | null>;
     }>;
+    readonly centerInline: (blockOffset: string) => readonly [Readonly<{
+        left: stylex.StyleXClassNameFor<"left", string>;
+        transform: stylex.StyleXClassNameFor<"transform", string>;
+    }>, stylex.InlineStyles];
 }>;
 //# sourceMappingURL=rtlStyles.d.ts.map

package/dist/utils/rtlStyles.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"rtlStyles.d.ts","sourceRoot":"","sources":["../../src/utils/rtlStyles.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,KAAK,MAAM,MAAM,kBAAkB,CAAC;AAE3C,eAAO,MAAM,SAAS;;;;EAIpB,CAAC"}
+{"version":3,"file":"rtlStyles.d.ts","sourceRoot":"","sources":["../../src/utils/rtlStyles.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AAEH,OAAO,KAAK,MAAM,MAAM,kBAAkB,CAAC;AAE3C,eAAO,MAAM,SAAS;;;;;;;;EASpB,CAAC"}

package/dist/utils/rtlStyles.js

@@ -4,8 +4,8 @@
  * @file rtlStyles.ts
  * @input None
  * @output Shared StyleX style that horizontally mirrors an element under RTL
- * @position Core utility; applied to directional-icon wrappers in Calendar,
- *   Lightbox, and the Table expand/disclosure plugins
+ * @position Core utility; applied to directional icons in Calendar, Lightbox,
+ *   Pagination, Carousel and the Table expand/disclosure plugins
  *
  * `mirror` flips its element on the horizontal axis only when an ancestor
  * carries `dir="rtl"`. Using `scaleX(-1)` (not `scale(-1, -1)`) keeps the
@@ -14,14 +14,39 @@
  * down when expanded under RTL. The `:is([dir="rtl"] *)` selector matches the
  * MobileNav drawer convention; a bare `direction: rtl` alone won't trigger it.
  *
+ * `centerInline(blockOffset?)` horizontally centers an absolutely-positioned,
+ * auto-width element on the inline axis, correctly in BOTH LTR and RTL, with an
+ * optional block-axis (Y) offset composed into the same transform. It
+ * intentionally uses PHYSICAL `left: 50%` + `translateX(-50%)`: both reference
+ * the same physical edge, so the pair is direction-symmetric and centers
+ * identically regardless of `dir`. A logical `insetInlineStart: 50%` would flip
+ * the anchor edge in RTL while the physical translate does not, leaving the
+ * element off-center by its own width (centered in LTR, broken in RTL). This is
+ * the one case where physical `left` is the correct choice, so the
+ * `no-physical-properties` suppression lives here ONCE rather than at each call
+ * site. The `@astryx/no-physical-properties` lint recognises this exact pattern
+ * and points offenders here.
+ *
+ * `blockOffset` is any CSS length/percentage for translateY (pass `'0px'` for
+ * none): e.g. `centerInline('100%')` sits the element one full height below its
+ * anchor, `centerInline('-50%')` centers it on both axes.
+ *
  * SYNC: When modified, update:
  * - /packages/core/src/utils/index.ts
  */
 
 import * as stylex from '@stylexjs/stylex';
+const _temp = {
+  kbCHJM: "x1nrll8i",
+  k3aq6I: "xsqj5wx",
+  "$$css": true
+};
 export const rtlStyles = {
   mirror: {
     k3aq6I: "xgtlewx",
     $$css: true
-  }
+  },
+  centerInline: blockOffset => [_temp, {
+    "--x-transform": `translate(-50%, ${blockOffset})` != null ? `translate(-50%, ${blockOffset})` : undefined
+  }]
 };

package/groups.doc.mjs

@@ -1,6 +1,6 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
-/** @type {import('./src/docs-types').GroupDoc} */
+/** @type {import('@astryxdesign/cli/authoring').ComponentGroupDoc} */
 
 /**
  * @file Group metadata for component categories that are not themselves components.
@@ -16,7 +16,7 @@
  * Or dynamically: `const {GROUP_DOCS} = await import('@astryxdesign/core/groups.doc.mjs')`
  */
 
-/** @type {Record<string, import('./src/docs-types').GroupDoc>} */
+/** @type {Record<string, import('@astryxdesign/cli/authoring').ComponentGroupDoc>} */
 export const GROUP_DOCS = {
   Chat: {
     name: 'Chat',