@dashforge/tw 0.1.0-beta → 0.2.0-beta

package/dist/src/components/Typography/Typography.d.ts

@@ -0,0 +1,42 @@
+import type { TypographyProps } from './typography.types.js';
+/**
+ * `<Typography>` — semantic typed text, the foundation of every readable
+ * surface in @dashforge/tw.
+ *
+ * Why this exists:
+ *   Tailwind ships a typographic scale (`text-xl`, `font-bold`,
+ *   `leading-relaxed`) but leaves the SEMANTIC HTML tag and the
+ *   intent-coloured palette to the consumer. That's fine for one-off
+ *   marketing surfaces, but at app scale it means every `<h2>` and every
+ *   body paragraph re-derives its own utility chain — and they drift.
+ *
+ *   Typography moves that decision into a typed prop set: the visual
+ *   scale, the intent colour, the alignment, the truncation all live in
+ *   `tailwind-variants` and resolve to the same utility chain everywhere
+ *   in the app. The default HTML tag is inferred from `variant` so the
+ *   semantic layer follows the visual layer; `as` and `asChild` are the
+ *   two escape hatches when you need something else.
+ *
+ * Layering:
+ *   • Sits BENEATH every component that renders text — `<Button>`'s
+ *     label, `<TextField>`'s helper text, MDX prose in our own docs.
+ *   • Composes ON TOP of `@dashforge/tw-tokens` colour scales (so
+ *     `color="primary"` paints `text-primary-700` in light, `-400` in dark,
+ *     reactive to `setMode()`).
+ *   • Polymorphic via Radix Slot — pairs cleanly with router `<Link>`,
+ *     `<button>`, or `<a>` without injecting an extra wrapper element.
+ *
+ * Polymorphism rules — `as` vs `asChild`:
+ *   • `as` swaps the rendered tag (we still render the element ourselves).
+ *   • `asChild` removes our element entirely — the single React child
+ *     becomes the rendered tag, with our className/ref merged onto it.
+ *     This is the Radix Slot pattern; use when you need a router Link
+ *     to style as a heading.
+ *   When BOTH are passed, `asChild` wins. We considered making this a
+ *   compile-time error via discriminated unions, but the API surface
+ *   already has 8 axes and adding one more dimension to the props type
+ *   would inflate IntelliSense suggestions for marginal benefit. The
+ *   runtime preference is documented; the test asserts it.
+ */
+export declare const Typography: import("react").ForwardRefExoticComponent<TypographyProps & import("react").RefAttributes<HTMLElement>>;
+//# sourceMappingURL=Typography.d.ts.map

package/dist/src/components/Typography/Typography.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Typography.d.ts","sourceRoot":"","sources":["../../../../src/components/Typography/Typography.tsx"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AA0B7D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AACH,eAAO,MAAM,UAAU,yGAwCtB,CAAC"}

package/dist/src/components/Typography/typography.types.d.ts

@@ -0,0 +1,61 @@
+import type { ElementType, HTMLAttributes } from 'react';
+import type { TypographyVariants } from './typography.variants.js';
+/**
+ * Props for `<Typography>`.
+ *
+ * Composition with native `HTMLAttributes`:
+ *   • `className` is omitted in favour of `sx` (string of utility classes)
+ *     — same convention as Button/TextField/Checkbox/Switch in this
+ *     package. `sx` is merged via `tailwind-merge`, so the consumer's
+ *     classes always win over variant defaults.
+ *   • `color` is omitted because the native HTML attribute (the
+ *     deprecated `color="red"` from HTML4) collides with our intent
+ *     prop — TypeScript would otherwise widen to a confusing union.
+ *
+ * Variant axes picked from `TypographyVariants`:
+ *   • `variant`  — the type scale (h1–h6, subtitle1/2, body1/2, caption, overline)
+ *   • `color`    — the intent (primary, secondary, success, warning, danger, info, neutral, muted, inherit)
+ *   • `weight`   — overrides the variant's default font-weight
+ *   • `align`    — text-align
+ *   • `truncate` — one-line ellipsis
+ *   • `noWrap`   — one-line without ellipsis
+ *   • `gutterBottom` — adds mb-3 (mirror of MUI's same prop)
+ *
+ * Polymorphism:
+ *   • `as` — override the HTML tag while keeping the variant's visual
+ *            style (e.g. `<Typography variant="h1" as="h2">` renders an
+ *            `<h2>` styled like h1 — useful when the semantic heading
+ *            level matters more than the type scale).
+ *   • `asChild` — render as the single child element via Radix Slot
+ *            (so the styles paint onto a `<Link>`, `<a>`, etc.).
+ *            Mutually exclusive with `as` — see component header for
+ *            the rationale.
+ */
+export interface TypographyProps extends Omit<HTMLAttributes<HTMLElement>, 'className' | 'color'>, Pick<TypographyVariants, 'variant' | 'color' | 'weight' | 'align' | 'truncate' | 'noWrap' | 'gutterBottom'> {
+    /**
+     * Override the HTML tag. Defaults to a sensible mapping per variant
+     * (h1→h1, …, body1→p, caption→span, overline→span). Use when the
+     * semantic heading level should differ from the visual scale —
+     * e.g. a "hero" rendered as an `<h2>` but styled like `h1`.
+     *
+     * Ignored when `asChild` is true.
+     */
+    as?: ElementType;
+    /**
+     * Render via Radix `Slot` — the Typography styles paint onto the
+     * single React child instead of wrapping it in our own tag. Useful
+     * for `<Typography asChild><Link>...</Link></Typography>` to get a
+     * styled router link with no extra DOM.
+     *
+     * Mutually exclusive with `as` (when both are passed, `asChild` wins
+     * and `as` is ignored — see Typography.tsx for the reason).
+     */
+    asChild?: boolean;
+    /**
+     * Utility classes appended to the variant chain. Resolved via
+     * `tailwind-merge` so the consumer's classes always win over the
+     * variant defaults — e.g. `sx="text-pink-500"` overrides `color="primary"`.
+     */
+    sx?: string;
+}
+//# sourceMappingURL=typography.types.d.ts.map

package/dist/src/components/Typography/typography.types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"typography.types.d.ts","sourceRoot":"","sources":["../../../../src/components/Typography/typography.types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,cAAc,EAAE,MAAM,OAAO,CAAC;AACzD,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,0BAA0B,CAAC;AAEnE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,MAAM,WAAW,eACf,SAAQ,IAAI,CAAC,cAAc,CAAC,WAAW,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,EACxD,IAAI,CAAC,kBAAkB,EAAE,SAAS,GAAG,OAAO,GAAG,QAAQ,GAAG,OAAO,GAAG,UAAU,GAAG,QAAQ,GAAG,cAAc,CAAC;IACnH;;;;;;;OAOG;IACH,EAAE,CAAC,EAAE,WAAW,CAAC;IAEjB;;;;;;;;OAQG;IACH,OAAO,CAAC,EAAE,OAAO,CAAC;IAElB;;;;OAIG;IACH,EAAE,CAAC,EAAE,MAAM,CAAC;CACb"}

package/dist/src/components/Typography/typography.variants.d.ts

@@ -0,0 +1,167 @@
+import { type VariantProps } from 'tailwind-variants';
+/**
+ * `typographyVariants` — the full type scale for the @dashforge/tw library.
+ *
+ * Mirrors the MUI Typography variant set (h1–h6 · subtitle1/2 · body1/2 ·
+ * caption · overline) so the mental model carries over for developers
+ * moving between the two ecosystems. Each variant baseline maps to a
+ * Tailwind utility chain that resolves through the @dashforge/tw-tokens
+ * scale (so the visual stays in sync with the rest of the system when the
+ * token theme is patched).
+ *
+ * Variant axes are intentionally ORTHOGONAL — `variant` chooses the type
+ * scale, `weight` overrides the variant's default weight (useful for "h2
+ * but lighter"), `color` picks the intent, `align` picks the axis. They
+ * never collide, so consumers can mix them freely.
+ *
+ * Two boolean flags (`truncate`, `noWrap`) encode the most common one-line
+ * patterns; `gutterBottom` adds the conventional bottom margin used when a
+ * heading precedes a paragraph block (mirror of MUI's same flag).
+ */
+export declare const typographyVariants: import("tailwind-variants").TVReturnType<{
+    variant: {
+        h1: string;
+        h2: string;
+        h3: string;
+        h4: string;
+        h5: string;
+        h6: string;
+        subtitle1: string;
+        subtitle2: string;
+        body1: string;
+        body2: string;
+        caption: string;
+        overline: string;
+    };
+    color: {
+        inherit: string;
+        primary: string;
+        secondary: string;
+        success: string;
+        warning: string;
+        danger: string;
+        info: string;
+        neutral: string;
+        muted: string;
+    };
+    weight: {
+        normal: string;
+        medium: string;
+        semibold: string;
+        bold: string;
+        extrabold: string;
+    };
+    align: {
+        left: string;
+        center: string;
+        right: string;
+        justify: string;
+    };
+    truncate: {
+        true: string;
+    };
+    noWrap: {
+        true: string;
+    };
+    gutterBottom: {
+        true: string;
+    };
+}, undefined, "text-inherit", {
+    variant: {
+        h1: string;
+        h2: string;
+        h3: string;
+        h4: string;
+        h5: string;
+        h6: string;
+        subtitle1: string;
+        subtitle2: string;
+        body1: string;
+        body2: string;
+        caption: string;
+        overline: string;
+    };
+    color: {
+        inherit: string;
+        primary: string;
+        secondary: string;
+        success: string;
+        warning: string;
+        danger: string;
+        info: string;
+        neutral: string;
+        muted: string;
+    };
+    weight: {
+        normal: string;
+        medium: string;
+        semibold: string;
+        bold: string;
+        extrabold: string;
+    };
+    align: {
+        left: string;
+        center: string;
+        right: string;
+        justify: string;
+    };
+    truncate: {
+        true: string;
+    };
+    noWrap: {
+        true: string;
+    };
+    gutterBottom: {
+        true: string;
+    };
+}, undefined, import("tailwind-variants").TVReturnType<{
+    variant: {
+        h1: string;
+        h2: string;
+        h3: string;
+        h4: string;
+        h5: string;
+        h6: string;
+        subtitle1: string;
+        subtitle2: string;
+        body1: string;
+        body2: string;
+        caption: string;
+        overline: string;
+    };
+    color: {
+        inherit: string;
+        primary: string;
+        secondary: string;
+        success: string;
+        warning: string;
+        danger: string;
+        info: string;
+        neutral: string;
+        muted: string;
+    };
+    weight: {
+        normal: string;
+        medium: string;
+        semibold: string;
+        bold: string;
+        extrabold: string;
+    };
+    align: {
+        left: string;
+        center: string;
+        right: string;
+        justify: string;
+    };
+    truncate: {
+        true: string;
+    };
+    noWrap: {
+        true: string;
+    };
+    gutterBottom: {
+        true: string;
+    };
+}, undefined, "text-inherit", unknown, unknown, undefined>>;
+export type TypographyVariants = VariantProps<typeof typographyVariants>;
+//# sourceMappingURL=typography.variants.d.ts.map

package/dist/src/components/Typography/typography.variants.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"typography.variants.d.ts","sourceRoot":"","sources":["../../../../src/components/Typography/typography.variants.ts"],"names":[],"mappings":"AAAA,OAAO,EAAM,KAAK,YAAY,EAAE,MAAM,mBAAmB,CAAC;AAE1D;;;;;;;;;;;;;;;;;;GAkBG;AACH,eAAO,MAAM,kBAAkB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;2DAyF7B,CAAC;AAEH,MAAM,MAAM,kBAAkB,GAAG,YAAY,CAAC,OAAO,kBAAkB,CAAC,CAAC"}

package/dist/src/components/VisuallyHidden/VisuallyHidden.d.ts

@@ -0,0 +1,42 @@
+import type { VisuallyHiddenProps } from './visuallyHidden.types.js';
+/**
+ * `<VisuallyHidden>` — the accessibility primitive.
+ *
+ * Hides children from sighted users (zero pixels rendered, no layout
+ * impact) while keeping them in the accessibility tree. Screen readers
+ * speak the content; voice control software uses it for click targets;
+ * keyboard users see nothing — same as if it weren't there.
+ *
+ * Implementation: Tailwind's built-in `sr-only` utility, which expands to:
+ *
+ *   .sr-only {
+ *     position: absolute;
+ *     width: 1px;
+ *     height: 1px;
+ *     padding: 0;
+ *     margin: -1px;
+ *     overflow: hidden;
+ *     clip: rect(0,0,0,0);
+ *     white-space: nowrap;
+ *     border-width: 0;
+ *   }
+ *
+ * This is the canonical "visually-hidden but screen-reader-accessible"
+ * pattern, also known as the WebAIM clip technique. Critically:
+ *
+ *   • NOT `display: none` (removes from a11y tree)
+ *   • NOT `visibility: hidden` (also removes from a11y tree)
+ *   • NOT `opacity: 0` (technically still rendered, doesn't help AT)
+ *   • NOT `width/height: 0` (collapses, some AT skips it)
+ *
+ * Default tag is `<span>` (inline) — the 99% case is "label inside a
+ * button or link". For block content, override with `as="div"`, but
+ * be aware nesting block inside inline is invalid HTML.
+ *
+ * The component is intentionally tiny (~30 LoC total): one className,
+ * one tag. The value is the COMPONENT NAME — `<VisuallyHidden>` reads
+ * as an intentional a11y decision in code review, while
+ * `className="sr-only"` looks like a typo or a forgotten utility.
+ */
+export declare const VisuallyHidden: import("react").ForwardRefExoticComponent<VisuallyHiddenProps & import("react").RefAttributes<HTMLElement>>;
+//# sourceMappingURL=VisuallyHidden.d.ts.map

package/dist/src/components/VisuallyHidden/VisuallyHidden.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"VisuallyHidden.d.ts","sourceRoot":"","sources":["../../../../src/components/VisuallyHidden/VisuallyHidden.tsx"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,2BAA2B,CAAC;AAErE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AACH,eAAO,MAAM,cAAc,6GAa1B,CAAC"}

package/dist/src/components/VisuallyHidden/visuallyHidden.types.d.ts

@@ -0,0 +1,42 @@
+import type { ElementType, HTMLAttributes, ReactElement } from 'react';
+/**
+ * Props for `<VisuallyHidden>` — the a11y primitive.
+ *
+ * Hides content visually (zero pixels rendered) while keeping it
+ * accessible to assistive technology (screen readers, voice control).
+ * The canonical use case: icon-only buttons that need an audible label
+ * for non-visual users.
+ *
+ *   <button>
+ *     <CloseIcon />
+ *     <VisuallyHidden>Close dialog</VisuallyHidden>
+ *   </button>
+ *
+ * Implementation uses Tailwind's `sr-only` utility, which sets
+ * `position: absolute; width: 1px; height: 1px; padding: 0;
+ * margin: -1px; overflow: hidden; clip: rect(0,0,0,0);
+ * white-space: nowrap; border-width: 0;` — the canonical
+ * "visually-hidden but screen-reader-accessible" pattern. Better
+ * than `display: none` (removes from a11y tree) and better than
+ * `visibility: hidden` (also removes from a11y tree).
+ */
+export interface VisuallyHiddenProps extends Omit<HTMLAttributes<HTMLElement>, 'className'> {
+    /**
+     * The text or markup hidden from sighted users but read by AT.
+     * Most often a string label.
+     */
+    children?: ReactElement | string | number;
+    /**
+     * Override the rendered HTML tag. Defaults to `'span'` — inline
+     * placement is the most common case (label inside a button or link).
+     * Use `as="div"` when the hidden content is block-level, but be
+     * aware: nesting a block inside an inline parent is invalid HTML.
+     */
+    as?: ElementType;
+    /**
+     * Utility classes appended to `sr-only`. RARELY needed for this
+     * primitive (it's just hidden text) — kept for API parity.
+     */
+    sx?: string;
+}
+//# sourceMappingURL=visuallyHidden.types.d.ts.map

package/dist/src/components/VisuallyHidden/visuallyHidden.types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"visuallyHidden.types.d.ts","sourceRoot":"","sources":["../../../../src/components/VisuallyHidden/visuallyHidden.types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,cAAc,EAAE,YAAY,EAAE,MAAM,OAAO,CAAC;AAEvE;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,MAAM,WAAW,mBACf,SAAQ,IAAI,CAAC,cAAc,CAAC,WAAW,CAAC,EAAE,WAAW,CAAC;IACtD;;;OAGG;IACH,QAAQ,CAAC,EAAE,YAAY,GAAG,MAAM,GAAG,MAAM,CAAC;IAE1C;;;;;OAKG;IACH,EAAE,CAAC,EAAE,WAAW,CAAC;IAEjB;;;OAGG;IACH,EAAE,CAAC,EAAE,MAAM,CAAC;CACb"}

package/dist/src/index.d.ts

@@ -71,6 +71,28 @@ export { confirmDialogVariants } from './components/ConfirmDialog/confirmDialog.
 export { SnackbarProvider, useSnackbar, } from './components/Snackbar/Snackbar.js';
 export type { SnackbarProviderProps, SnackbarApi, SnackbarOptions, SnackbarRecord, SnackbarSeverity, SnackbarPosition, SnackbarSlotProps, } from './components/Snackbar/snackbar.types.js';
 export { snackbarVariants } from './components/Snackbar/snackbar.variants.js';
+export { Typography } from './components/Typography/Typography.js';
+export type { TypographyProps } from './components/Typography/typography.types.js';
+export { typographyVariants } from './components/Typography/typography.variants.js';
+export { Box } from './components/Box/Box.js';
+export type { BoxProps } from './components/Box/box.types.js';
+export { boxVariants } from './components/Box/box.variants.js';
+export { Stack } from './components/Stack/Stack.js';
+export type { StackProps } from './components/Stack/stack.types.js';
+export { stackVariants } from './components/Stack/stack.variants.js';
+export { Grid } from './components/Grid/Grid.js';
+export type { GridProps, GridContainerProps, GridItemProps, ColSpan, GridSpacingStep, } from './components/Grid/grid.types.js';
+export { gridVariants } from './components/Grid/grid.variants.js';
+export { Container } from './components/Container/Container.js';
+export type { ContainerProps } from './components/Container/container.types.js';
+export { containerVariants } from './components/Container/container.variants.js';
+export { Divider } from './components/Divider/Divider.js';
+export type { DividerProps } from './components/Divider/divider.types.js';
+export { dividerVariants, dividerLineVariants, } from './components/Divider/divider.variants.js';
+export { AspectRatio } from './components/AspectRatio/AspectRatio.js';
+export type { AspectRatioProps } from './components/AspectRatio/aspectRatio.types.js';
+export { VisuallyHidden } from './components/VisuallyHidden/VisuallyHidden.js';
+export type { VisuallyHiddenProps } from './components/VisuallyHidden/visuallyHidden.types.js';
 export { useAccessState } from './hooks/useAccessState.js';
 export { cn } from './utils/cn.js';
 export { tv } from 'tailwind-variants';

package/dist/src/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAGH,OAAO,EAAE,MAAM,EAAE,MAAM,+BAA+B,CAAC;AACvD,YAAY,EAAE,WAAW,EAAE,MAAM,qCAAqC,CAAC;AACvE,OAAO,EAAE,cAAc,EAAE,MAAM,wCAAwC,CAAC;AAExE,OAAO,EAAE,SAAS,EAAE,MAAM,qCAAqC,CAAC;AAChE,YAAY,EACV,cAAc,EACd,kBAAkB,GACnB,MAAM,2CAA2C,CAAC;AACnD,OAAO,EAAE,iBAAiB,EAAE,MAAM,8CAA8C,CAAC;AAEjF,OAAO,EAAE,QAAQ,EAAE,MAAM,mCAAmC,CAAC;AAC7D,YAAY,EACV,aAAa,EACb,iBAAiB,GAClB,MAAM,yCAAyC,CAAC;AACjD,OAAO,EAAE,gBAAgB,EAAE,MAAM,4CAA4C,CAAC;AAE9E,OAAO,EAAE,MAAM,EAAE,MAAM,+BAA+B,CAAC;AACvD,YAAY,EACV,WAAW,EACX,eAAe,GAChB,MAAM,qCAAqC,CAAC;AAC7C,OAAO,EAAE,cAAc,EAAE,MAAM,wCAAwC,CAAC;AAIxE,OAAO,EAAE,UAAU,EAAE,MAAM,uCAAuC,CAAC;AACnE,YAAY,EACV,eAAe,EACf,gBAAgB,EAChB,mBAAmB,GACpB,MAAM,6CAA6C,CAAC;AACrD,OAAO,EAAE,kBAAkB,EAAE,MAAM,gDAAgD,CAAC;AAEpF,OAAO,EAAE,QAAQ,EAAE,MAAM,mCAAmC,CAAC;AAC7D,YAAY,EACV,aAAa,EACb,iBAAiB,GAClB,MAAM,yCAAyC,CAAC;AACjD,OAAO,EAAE,gBAAgB,EAAE,MAAM,4CAA4C,CAAC;AAI9E,OAAO,EAAE,WAAW,EAAE,MAAM,yCAAyC,CAAC;AACtE,YAAY,EACV,gBAAgB,EAChB,oBAAoB,GACrB,MAAM,+CAA+C,CAAC;AACvD,OAAO,EAAE,mBAAmB,EAAE,MAAM,kDAAkD,CAAC;AAEvF,OAAO,EAAE,QAAQ,EAAE,MAAM,mCAAmC,CAAC;AAC7D,YAAY,EACV,aAAa,EACb,iBAAiB,EACjB,YAAY,GACb,MAAM,yCAAyC,CAAC;AACjD,OAAO,EAAE,gBAAgB,EAAE,MAAM,4CAA4C,CAAC;AAI9E,OAAO,EAAE,YAAY,EAAE,MAAM,2CAA2C,CAAC;AACzE,YAAY,EACV,iBAAiB,EACjB,kBAAkB,EAClB,qBAAqB,EACrB,iBAAiB,GAClB,MAAM,iDAAiD,CAAC;AACzD,OAAO,EAAE,oBAAoB,EAAE,MAAM,oDAAoD,CAAC;AAI1F,OAAO,EACL,cAAc,EACd,eAAe,GAChB,MAAM,+CAA+C,CAAC;AACvD,YAAY,EACV,mBAAmB,EACnB,kBAAkB,EAClB,uBAAuB,GACxB,MAAM,qDAAqD,CAAC;AAC7D,OAAO,EAAE,sBAAsB,EAAE,MAAM,wDAAwD,CAAC;AAIhG,OAAO,EAAE,WAAW,EAAE,MAAM,yCAAyC,CAAC;AACtE,YAAY,EACV,gBAAgB,EAChB,cAAc,EACd,oBAAoB,EACpB,uBAAuB,GACxB,MAAM,+CAA+C,CAAC;AACvD,OAAO,EAAE,mBAAmB,EAAE,MAAM,kDAAkD,CAAC;AAEvF,OAAO,EAAE,OAAO,EAAE,MAAM,iCAAiC,CAAC;AAC1D,YAAY,EACV,YAAY,EACZ,WAAW,EACX,WAAW,EACX,YAAY,EACZ,gBAAgB,EAChB,oBAAoB,GACrB,MAAM,uCAAuC,CAAC;AAC/C,OAAO,EAAE,eAAe,EAAE,MAAM,0CAA0C,CAAC;AAE3E,OAAO,EAAE,MAAM,EAAE,MAAM,+BAA+B,CAAC;AACvD,YAAY,EACV,WAAW,EACX,eAAe,GAChB,MAAM,qCAAqC,CAAC;AAC7C,OAAO,EAAE,cAAc,EAAE,MAAM,wCAAwC,CAAC;AAExE,OAAO,EAAE,QAAQ,EAAE,MAAM,mCAAmC,CAAC;AAC7D,YAAY,EACV,aAAa,EACb,iBAAiB,GAClB,MAAM,yCAAyC,CAAC;AACjD,OAAO,EAAE,gBAAgB,EAAE,MAAM,4CAA4C,CAAC;AAI9E,OAAO,EACL,qBAAqB,EACrB,UAAU,GACX,MAAM,6CAA6C,CAAC;AACrD,YAAY,EACV,0BAA0B,EAC1B,sBAAsB,EACtB,SAAS,EACT,cAAc,EACd,eAAe,GAChB,MAAM,mDAAmD,CAAC;AAC3D,OAAO,EAAE,qBAAqB,EAAE,MAAM,sDAAsD,CAAC;AAE7F,OAAO,EACL,gBAAgB,EAChB,WAAW,GACZ,MAAM,mCAAmC,CAAC;AAC3C,YAAY,EACV,qBAAqB,EACrB,WAAW,EACX,eAAe,EACf,cAAc,EACd,gBAAgB,EAChB,gBAAgB,EAChB,iBAAiB,GAClB,MAAM,yCAAyC,CAAC;AACjD,OAAO,EAAE,gBAAgB,EAAE,MAAM,4CAA4C,CAAC;AAG9E,OAAO,EAAE,cAAc,EAAE,MAAM,2BAA2B,CAAC;AAG3D,OAAO,EAAE,EAAE,EAAE,MAAM,eAAe,CAAC;AAInC,OAAO,EAAE,EAAE,EAAE,MAAM,mBAAmB,CAAC;AACvC,YAAY,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AAEtD;;GAEG;AACH,eAAO,MAAM,OAAO,eAAe,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dashforge/tw",
-  "version": "0.1.0-beta",
+  "version": "0.2.0-beta",
   "private": false,
   "type": "module",
   "main": "./dist/index.esm.js",
@@ -26,8 +26,8 @@
     "tailwind-variants": "^3.1.1",
     "vitest": "*",
     "@dashforge/forms": "0.2.3-beta",
-    "@dashforge/ui-core": "0.2.3-beta",
-    "@dashforge/rbac": "0.2.3-beta"
+    "@dashforge/rbac": "0.2.3-beta",
+    "@dashforge/ui-core": "0.2.3-beta"
   },
   "peerDependencies": {
     "react": "^18.0.0 || ^19.0.0",

package/src/components/AspectRatio/AspectRatio.test.tsx

@@ -0,0 +1,173 @@
+// @vitest-environment jsdom
+import { describe, it, expect } from 'vitest';
+import { render } from '@testing-library/react';
+import { AspectRatio } from './AspectRatio.js';
+
+describe('<AspectRatio>', () => {
+  // ─── Default rendering ──────────────────────────────────────────────
+  describe('default rendering', () => {
+    it('renders a <div> by default', () => {
+      const { container } = render(<AspectRatio>x</AspectRatio>);
+      expect(container.firstElementChild?.tagName).toBe('DIV');
+    });
+
+    it('default ratio is 1 (square)', () => {
+      const { container } = render(<AspectRatio>x</AspectRatio>);
+      const el = container.firstElementChild as HTMLElement;
+      expect(el.style.aspectRatio).toBe('1 / 1');
+    });
+
+    it('always has w-full baseline', () => {
+      const { container } = render(<AspectRatio>x</AspectRatio>);
+      expect(container.firstElementChild?.className).toContain('w-full');
+    });
+  });
+
+  // ─── ratio prop ─────────────────────────────────────────────────────
+  describe('ratio', () => {
+    it('numeric ratio 16/9 → "1.7777… / 1"', () => {
+      const { container } = render(<AspectRatio ratio={16 / 9}>x</AspectRatio>);
+      const el = container.firstElementChild as HTMLElement;
+      // 16/9 ≈ 1.7777, formatted as "<number> / 1"
+      expect(el.style.aspectRatio).toMatch(/^1\.\d+ \/ 1$/);
+    });
+
+    it('numeric ratio 4/3', () => {
+      const { container } = render(<AspectRatio ratio={4 / 3}>x</AspectRatio>);
+      const el = container.firstElementChild as HTMLElement;
+      expect(el.style.aspectRatio).toMatch(/^1\.\d+ \/ 1$/);
+    });
+
+    it('string ratio "16 / 9" passes through', () => {
+      const { container } = render(<AspectRatio ratio="16 / 9">x</AspectRatio>);
+      const el = container.firstElementChild as HTMLElement;
+      expect(el.style.aspectRatio).toBe('16 / 9');
+    });
+
+    it('string ratio "21/9" passes through (ultrawide)', () => {
+      const { container } = render(<AspectRatio ratio="21/9">x</AspectRatio>);
+      const el = container.firstElementChild as HTMLElement;
+      expect(el.style.aspectRatio).toBe('21/9');
+    });
+  });
+
+  // ─── Override ───────────────────────────────────────────────────────
+  describe('override', () => {
+    it('sx adds utility classes', () => {
+      const { container } = render(
+        <AspectRatio ratio={16 / 9} sx="rounded-xl overflow-hidden">
+          x
+        </AspectRatio>,
+      );
+      const cls = container.firstElementChild?.className ?? '';
+      expect(cls).toContain('rounded-xl');
+      expect(cls).toContain('overflow-hidden');
+    });
+
+    it('user style merges with aspect-ratio', () => {
+      const { container } = render(
+        <AspectRatio ratio={1} style={{ backgroundColor: 'red' }}>x</AspectRatio>,
+      );
+      const el = container.firstElementChild as HTMLElement;
+      expect(el.style.backgroundColor).toBe('red');
+      expect(el.style.aspectRatio).toBe('1 / 1');
+    });
+
+    it('user style aspect-ratio overrides the prop (last wins)', () => {
+      const { container } = render(
+        <AspectRatio ratio={1} style={{ aspectRatio: '2 / 1' }}>x</AspectRatio>,
+      );
+      const el = container.firstElementChild as HTMLElement;
+      // Inline style merge — user's later spread wins
+      expect(el.style.aspectRatio).toBe('2 / 1');
+    });
+  });
+
+  // ─── Polymorphism ───────────────────────────────────────────────────
+  describe('polymorphism', () => {
+    it('as="figure" renders <figure>', () => {
+      const { container } = render(
+        <AspectRatio as="figure" ratio={1}>x</AspectRatio>,
+      );
+      expect(container.firstElementChild?.tagName).toBe('FIGURE');
+    });
+
+    it('as="picture" works for responsive image markup', () => {
+      const { container } = render(
+        <AspectRatio as="picture" ratio={16 / 9}>
+          <img src="x.jpg" alt="" />
+        </AspectRatio>,
+      );
+      expect(container.firstElementChild?.tagName).toBe('PICTURE');
+    });
+  });
+
+  // ─── Child rendering ────────────────────────────────────────────────
+  describe('child rendering', () => {
+    it('renders an <img> child', () => {
+      const { container } = render(
+        <AspectRatio ratio={16 / 9}>
+          <img src="hero.jpg" alt="hero" className="w-full h-full object-cover" />
+        </AspectRatio>,
+      );
+      const img = container.querySelector('img');
+      expect(img?.getAttribute('src')).toBe('hero.jpg');
+    });
+
+    it('renders multiple children (e.g. overlay pattern)', () => {
+      const { container } = render(
+        <AspectRatio ratio={16 / 9}>
+          <img src="hero.jpg" alt="hero" />
+          <div className="absolute inset-0 bg-black/40" />
+        </AspectRatio>,
+      );
+      expect(container.firstElementChild?.children.length).toBe(2);
+    });
+  });
+
+  // ─── Pass-through ───────────────────────────────────────────────────
+  it('forwards data-* + aria-*', () => {
+    const { container } = render(
+      <AspectRatio data-testid="ar" aria-label="hero">x</AspectRatio>,
+    );
+    const el = container.firstElementChild;
+    expect(el?.getAttribute('data-testid')).toBe('ar');
+    expect(el?.getAttribute('aria-label')).toBe('hero');
+  });
+
+  // ─── F11-bis edge cases ─────────────────────────────────────────────
+  describe('extreme ratio values', () => {
+    it('ratio="21 / 9" (ultrawide cinema) passes through verbatim', () => {
+      const { container } = render(<AspectRatio ratio="21 / 9">x</AspectRatio>);
+      expect((container.firstElementChild as HTMLElement).style.aspectRatio).toBe('21 / 9');
+    });
+
+    it('ratio="9 / 16" (portrait video) passes through verbatim', () => {
+      const { container } = render(<AspectRatio ratio="9 / 16">x</AspectRatio>);
+      expect((container.firstElementChild as HTMLElement).style.aspectRatio).toBe('9 / 16');
+    });
+
+    it('numeric tiny ratio (0.5) formats as "0.5 / 1"', () => {
+      const { container } = render(<AspectRatio ratio={0.5}>x</AspectRatio>);
+      expect((container.firstElementChild as HTMLElement).style.aspectRatio).toBe('0.5 / 1');
+    });
+
+    it('numeric large ratio (3) formats as "3 / 1"', () => {
+      const { container } = render(<AspectRatio ratio={3}>x</AspectRatio>);
+      expect((container.firstElementChild as HTMLElement).style.aspectRatio).toBe('3 / 1');
+    });
+  });
+
+  describe('rounded clipped media pattern (the #1 doc gotcha)', () => {
+    it('rounded + overflow-hidden both end up on the className', () => {
+      const { container } = render(
+        <AspectRatio ratio={16 / 9} sx="rounded-2xl overflow-hidden">
+          <img src="x.jpg" alt="" className="w-full h-full object-cover" />
+        </AspectRatio>,
+      );
+      const cls = container.firstElementChild?.className ?? '';
+      expect(cls).toContain('rounded-2xl');
+      expect(cls).toContain('overflow-hidden');
+    });
+  });
+});