@instruments/materia-ui 0.1.0

package/dist/tokens/responsive-classes.js

@@ -0,0 +1,321 @@
+/**
+ * Pre-defined class maps for responsive utilities.
+ * All classes are spelled out explicitly for Tailwind static analysis.
+ */
+import { COMPONENT_SIZES } from "./size.js";
+// ============================================================================
+// GAP CLASSES
+// ============================================================================
+/** Extended gap size including none and 3xs */
+export const GAP_SIZES = ["none", "3xs", ...COMPONENT_SIZES];
+/**
+ * GAP_CLASS utility.
+ */
+export const GAP_CLASS = {
+    "2xl": "gap-8",
+    "2xs": "gap-1",
+    "3xl": "gap-10",
+    "3xs": "gap-0.5",
+    base: "gap-4",
+    lg: "gap-5",
+    none: "gap-0",
+    sm: "gap-3",
+    xl: "gap-6",
+    xs: "gap-2",
+};
+/**
+ * GAP_X_CLASS utility.
+ */
+export const GAP_X_CLASS = {
+    "2xl": "gap-x-8",
+    "2xs": "gap-x-1",
+    "3xl": "gap-x-10",
+    "3xs": "gap-x-0.5",
+    base: "gap-x-4",
+    lg: "gap-x-5",
+    none: "gap-x-0",
+    sm: "gap-x-3",
+    xl: "gap-x-6",
+    xs: "gap-x-2",
+};
+/**
+ * GAP_Y_CLASS utility.
+ */
+export const GAP_Y_CLASS = {
+    "2xl": "gap-y-8",
+    "2xs": "gap-y-1",
+    "3xl": "gap-y-10",
+    "3xs": "gap-y-0.5",
+    base: "gap-y-4",
+    lg: "gap-y-5",
+    none: "gap-y-0",
+    sm: "gap-y-3",
+    xl: "gap-y-6",
+    xs: "gap-y-2",
+};
+// ============================================================================
+// FLEX DIRECTION CLASSES
+// ============================================================================
+/**
+ * DIRECTION_CLASS utility.
+ */
+export const DIRECTION_CLASS = {
+    column: "flex-col",
+    "column-reverse": "flex-col-reverse",
+    row: "flex-row",
+    "row-reverse": "flex-row-reverse",
+};
+// ============================================================================
+// JUSTIFY CLASSES
+// ============================================================================
+/**
+ * JUSTIFY_CLASS utility.
+ */
+export const JUSTIFY_CLASS = {
+    center: "justify-center",
+    "flex-end": "justify-end",
+    "flex-start": "justify-start",
+    "space-around": "justify-around",
+    "space-between": "justify-between",
+    "space-evenly": "justify-evenly",
+};
+// ============================================================================
+// ALIGN CLASSES
+// ============================================================================
+/**
+ * ALIGN_CLASS utility.
+ */
+export const ALIGN_CLASS = {
+    baseline: "items-baseline",
+    center: "items-center",
+    "flex-end": "items-end",
+    "flex-start": "items-start",
+    stretch: "items-stretch",
+};
+// ============================================================================
+// WRAP CLASSES
+// ============================================================================
+/**
+ * WRAP_CLASS utility.
+ */
+export const WRAP_CLASS = {
+    nowrap: "flex-nowrap",
+    wrap: "flex-wrap",
+    "wrap-reverse": "flex-wrap-reverse",
+};
+// ============================================================================
+// GRID COLUMN CLASSES
+// ============================================================================
+/**
+ * GRID_COLS_CLASS utility.
+ */
+export const GRID_COLS_CLASS = {
+    1: "grid-cols-1",
+    10: "grid-cols-10",
+    11: "grid-cols-11",
+    12: "grid-cols-12",
+    2: "grid-cols-2",
+    3: "grid-cols-3",
+    4: "grid-cols-4",
+    5: "grid-cols-5",
+    6: "grid-cols-6",
+    7: "grid-cols-7",
+    8: "grid-cols-8",
+    9: "grid-cols-9",
+};
+// ============================================================================
+// GRID COLUMN SPAN CLASSES
+// ============================================================================
+/**
+ * COL_SPAN_CLASS utility.
+ */
+export const COL_SPAN_CLASS = {
+    1: "col-span-1",
+    10: "col-span-10",
+    11: "col-span-11",
+    12: "col-span-12",
+    2: "col-span-2",
+    3: "col-span-3",
+    4: "col-span-4",
+    5: "col-span-5",
+    6: "col-span-6",
+    7: "col-span-7",
+    8: "col-span-8",
+    9: "col-span-9",
+    auto: "col-auto",
+    full: "col-span-full",
+};
+// ============================================================================
+// GRID COLUMN START (OFFSET) CLASSES
+// ============================================================================
+/**
+ * COL_START_CLASS utility.
+ */
+export const COL_START_CLASS = {
+    1: "col-start-1",
+    10: "col-start-10",
+    11: "col-start-11",
+    12: "col-start-12",
+    13: "col-start-13",
+    2: "col-start-2",
+    3: "col-start-3",
+    4: "col-start-4",
+    5: "col-start-5",
+    6: "col-start-6",
+    7: "col-start-7",
+    8: "col-start-8",
+    9: "col-start-9",
+    auto: "col-start-auto",
+};
+// ============================================================================
+// WIDTH CLASSES (for Space component)
+// ============================================================================
+/**
+ * WIDTH_CLASS utility.
+ */
+export const WIDTH_CLASS = {
+    "2xl": "w-8",
+    "2xs": "w-1",
+    "3xl": "w-10",
+    base: "w-4",
+    lg: "w-5",
+    sm: "w-3",
+    xl: "w-6",
+    xs: "w-2",
+};
+// ============================================================================
+// HEIGHT CLASSES (for Space component)
+// ============================================================================
+/**
+ * HEIGHT_CLASS utility.
+ */
+export const HEIGHT_CLASS = {
+    "2xl": "h-8",
+    "2xs": "h-1",
+    "3xl": "h-10",
+    base: "h-4",
+    lg: "h-5",
+    sm: "h-3",
+    xl: "h-6",
+    xs: "h-2",
+};
+// ============================================================================
+// PADDING CLASSES (for Container component)
+// ============================================================================
+/**
+ * PADDING_X_CLASS utility.
+ */
+export const PADDING_X_CLASS = {
+    "2xl": "px-8",
+    "2xs": "px-1",
+    "3xl": "px-10",
+    base: "px-4",
+    lg: "px-5",
+    sm: "px-3",
+    xl: "px-6",
+    xs: "px-2",
+};
+/**
+ * PADDING_Y_CLASS utility.
+ */
+export const PADDING_Y_CLASS = {
+    "2xl": "py-8",
+    "2xs": "py-1",
+    "3xl": "py-10",
+    base: "py-4",
+    lg: "py-5",
+    sm: "py-3",
+    xl: "py-6",
+    xs: "py-2",
+};
+/**
+ * CARD_INSET_CLASS utility. Each class sets `--card-inset`, which the Card root
+ * and its parts read. Defined as `@utility` rules in styles/index.css.
+ */
+export const CARD_INSET_CLASS = {
+    "2xl": "card-inset-2xl",
+    "2xs": "card-inset-2xs",
+    "3xl": "card-inset-3xl",
+    base: "card-inset-base",
+    lg: "card-inset-lg",
+    none: "card-inset-none",
+    sm: "card-inset-sm",
+    xl: "card-inset-xl",
+    xs: "card-inset-xs",
+};
+// ============================================================================
+// MAX-WIDTH CLASSES (for Container component)
+// ============================================================================
+/**
+ * MAX_WIDTH_CLASS utility.
+ */
+export const MAX_WIDTH_CLASS = {
+    "2xl": "max-w-4xl",
+    "2xs": "max-w-xs",
+    "3xl": "max-w-6xl",
+    base: "max-w-lg",
+    lg: "max-w-xl",
+    sm: "max-w-md",
+    xl: "max-w-2xl",
+    xs: "max-w-sm",
+};
+/**
+ * Canonical page gutter shared by the Container and Section page shells:
+ * `px-4` collapsing to `px-6` from the `sm` breakpoint. Matches the de-facto
+ * app-frame literal used across brands and admin pages.
+ */
+export const PAGE_GUTTER_INSET = {
+    base: "base",
+    sm: "xl",
+};
+/**
+ * CONTAINER_SIZE_CLASS utility.
+ */
+export const CONTAINER_SIZE_CLASS = {
+    "2xl": "max-w-2xl",
+    "3xl": "max-w-3xl",
+    "4xl": "max-w-4xl",
+    "5xl": "max-w-5xl",
+    "6xl": "max-w-6xl",
+    "7xl": "max-w-7xl",
+    full: "max-w-full",
+    lg: "max-w-lg",
+    md: "max-w-md",
+    prose: "max-w-prose",
+    sm: "max-w-sm",
+    xl: "max-w-xl",
+    xs: "max-w-xs",
+};
+/**
+ * SECTION_SPACE_CLASS utility.
+ */
+export const SECTION_SPACE_CLASS = {
+    "2xl": "py-16",
+    "3xl": "py-24",
+    base: "py-6",
+    lg: "py-8",
+    none: "py-0",
+    sm: "py-4",
+    xl: "py-12",
+    xs: "py-2",
+};
+/**
+ * ORDER_CLASS utility.
+ */
+export const ORDER_CLASS = {
+    1: "order-1",
+    10: "order-10",
+    11: "order-11",
+    12: "order-12",
+    2: "order-2",
+    3: "order-3",
+    4: "order-4",
+    5: "order-5",
+    6: "order-6",
+    7: "order-7",
+    8: "order-8",
+    9: "order-9",
+    first: "order-first",
+    last: "order-last",
+    none: "order-0",
+};

package/dist/tokens/responsive.d.ts

@@ -0,0 +1,168 @@
+import type { Breakpoint } from "./breakpoint.js";
+/**
+ * Mode for responsive classes - either screen (viewport) or container queries.
+ */
+export type ResponsiveMode = "screen" | "container";
+/**
+ * A value that is either a single static value or a responsive object whose
+ * keys are viewport breakpoints AND/OR `@`-prefixed container-query variants,
+ * freely mixed. Used throughout the design system for per-breakpoint overrides
+ * of props like `size`, `gap`, `columns`, `direction`, etc.
+ *
+ * @example
+ * // Static value - same everywhere
+ * const gap: ResponsiveValue<Size> = "4";
+ *
+ * @example
+ * // Viewport breakpoints
+ * const gap: ResponsiveValue<Size> = { base: "2", md: "4", xl: "6" };
+ *
+ * @example
+ * // Viewport + container query in one object
+ * const size: ResponsiveValue<Size> = { base: "sm", md: "base", "@sm": "xl" };
+ */
+export type ResponsiveValue<T> = T | ResponsiveObject<T>;
+/**
+ * The breakpoint-keyed object of a {@link LayoutResponsiveValue}: `base` plus
+ * any viewport breakpoint name, and nothing else. Container-query keys (`@md`)
+ * are not part of it, so passing one is a type error, even alongside valid keys.
+ */
+export type LayoutResponsiveObject<T> = Partial<Record<Breakpoint, T>> & {
+    base?: T;
+} & {
+    [K in ContainerQueryKey]?: never;
+};
+/**
+ * A value that is either static or an object keyed by breakpoint name only.
+ * The type of every layout prop (`gap`, `cols`, `span`, `direction`, `inset`,
+ * ...). Layout props resolve through {@link getResponsiveClasses}, which reads
+ * breakpoint names only; `responsiveMode="container"` switches those same
+ * names to container queries. Mixed `@`-keys are honoured only by component
+ * `size` props, which use {@link ResponsiveValue}.
+ *
+ * @example
+ * const gap: LayoutResponsiveValue<GapSize> = { base: "sm", md: "lg" };
+ */
+export type LayoutResponsiveValue<T> = T | LayoutResponsiveObject<T>;
+/**
+ * Screen breakpoint prefixes (viewport media queries)
+ */
+export declare const SCREEN_PREFIX: Record<Breakpoint, string>;
+/**
+ * Container query prefixes
+ */
+export declare const CONTAINER_PREFIX: Record<Breakpoint, string>;
+/** True only in a local-dev browser session - gates noisy consumer-misuse warnings. */
+export declare const isLocalDevBrowser: () => boolean;
+/**
+ * Check if a value is a responsive object (vs a bare static value).
+ */
+export declare const isResponsiveValue: <T>(value: ResponsiveValue<T> | undefined) => value is ResponsiveObject<T>;
+/**
+ * Returns the Tailwind class prefix for a given breakpoint and responsive mode.
+ *
+ * In `"screen"` mode, returns viewport prefixes like `"md:"`.
+ * In `"container"` mode, returns container-query prefixes like `"@md:"`.
+ * The `"base"` breakpoint always returns an empty string.
+ *
+ * @param breakpoint - Target breakpoint name
+ * @param mode - `"screen"` (default) for viewport media queries, `"container"` for container queries
+ * @returns The Tailwind prefix string (e.g., `"lg:"`, `"@lg:"`, or `""` for base)
+ */
+export declare const getBreakpointPrefix: (breakpoint: Breakpoint, mode?: ResponsiveMode) => string;
+/**
+ * Generate responsive classes from a value and class map
+ *
+ * @param value - Static value or responsive object
+ * @param classMap - Map of value to class name (without breakpoint prefix)
+ * @param mode - "screen" (default) or "container"
+ * @returns Array of class names with appropriate breakpoint prefixes
+ *
+ * @example
+ * ```ts
+ * const GAP_CLASS = { xs: "gap-2", sm: "gap-3", base: "gap-4" };
+ * getResponsiveClasses("base", GAP_CLASS, "screen");
+ * // → ["gap-4"]
+ *
+ * getResponsiveClasses({ base: "xs", md: "base" }, GAP_CLASS, "screen");
+ * // → ["gap-2", "md:gap-4"]
+ *
+ * getResponsiveClasses({ base: "xs", md: "base" }, GAP_CLASS, "container");
+ * // → ["gap-2", "@md:gap-4"]
+ * ```
+ */
+export declare const getResponsiveClasses: <T extends string | number>(value: LayoutResponsiveValue<T> | undefined, classMap: Record<T, string>, mode?: ResponsiveMode) => string[];
+/**
+ * A container-query key: an `@`-prefixed variant used verbatim as a Tailwind
+ * variant prefix - a standard container breakpoint (`@sm`, `@lg`) or an
+ * arbitrary/named one (`@[240px]/card`).
+ */
+export type ContainerQueryKey = `@${string}`;
+/**
+ * A responsive value whose object keys may be viewport breakpoints AND/OR
+ * `@`-prefixed container-query variants, freely mixed in one object - e.g.
+ * `{ base: "sm", lg: "base", "@sm": "xl" }`. Bare keys resolve to viewport
+ * media queries (`lg:`); `@`-keys to container queries (`@sm:`), which respond
+ * to the nearest `@container` ancestor rather than the viewport.
+ *
+ * Optional per-key literal overrides (see the resolver's `literalOverrides`
+ * param) back arbitrary container keys whose prefixed classes cannot be
+ * safelisted.
+ */
+export type ResponsiveObject<T> = Partial<Record<Breakpoint | ContainerQueryKey, T>> & {
+    base?: T;
+};
+/**
+ * Resolve a responsive value whose class map holds MULTI-class strings (e.g. a
+ * component `size` scale like `"h-9 px-3 text-sm"`).
+ *
+ * Unlike {@link getResponsiveClasses} - which prefixes only the first token and
+ * is meant for single-class layout maps - this prefixes EVERY token per
+ * breakpoint (`md:h-10 md:px-4 md:text-sm`), so each utility actually responds.
+ * A static value returns its base classes; an object resolves `base` (or
+ * `fallback`) unprefixed, then appends each breakpoint's classes so larger
+ * breakpoints win by media-query specificity.
+ *
+ * Object keys may be viewport breakpoints AND/OR `@`-prefixed container-query
+ * keys, freely mixed (`{ base: "sm", lg: "base", "@sm": "xl" }`). Bare keys →
+ * media queries; `@`-keys → container queries; on a tie the container key wins
+ * (emitted last - see {@link orderedResponsiveEntries}).
+ *
+ * IMPORTANT: the prefixed combinations must exist in the compiled CSS. Tailwind
+ * cannot statically see these runtime concatenations, so the viewport AND
+ * container size combos are force-emitted by the `@source inline(...)` safelist
+ * in shared-styles.css. Arbitrary/named container keys (`@[240px]/card`) cannot
+ * be safelisted - pass their fully-prefixed class strings via `literalOverrides`
+ * (keyed `"<key>:<sizeValue>"`) so the scanner sees them as literals.
+ *
+ * @param value - Static size or a mixed viewport/container responsive object
+ * @param classMap - Map of size → (multi-class) class string
+ * @param fallback - Size used for `base` when the object omits it (the component default)
+ * @param literalOverrides - Optional literal class strings for arbitrary container keys
+ */
+export declare const getResponsiveSizeClasses: <T extends string>(value: ResponsiveValue<T> | undefined, classMap: Record<T, string>, fallback: T, literalOverrides?: Partial<Record<string, string>>) => string;
+/**
+ * Resolve the base {@link ComponentSize}-style value for a responsive prop:
+ * the object's `base` key, the static value itself, or the `fallback`.
+ * Pass this to cva so `defaultVariants` + size-dependent `compoundVariants`
+ * still resolve for the base breakpoint.
+ */
+export declare const resolveResponsiveBase: <T extends string>(value: ResponsiveValue<T> | undefined, fallback: T) => T;
+/**
+ * Like {@link getResponsiveSizeClasses} but returns ONLY the non-base
+ * overrides (a static value → `""`). Use when cva already applies the base size
+ * (and its compoundVariants) via {@link resolveResponsiveBase}, and you only
+ * need to layer `md:…`/`@sm:…` overrides on top. Supports mixed viewport/
+ * container keys and the same `literalOverrides`.
+ */
+export declare const getResponsiveSizeOverrides: <T extends string>(value: ResponsiveValue<T> | undefined, classMap: Record<T, string>, literalOverrides?: Partial<Record<string, string>>) => string;
+/**
+ * Push responsive classes to an array (mutates the array)
+ * Convenience wrapper around getResponsiveClasses for the pattern used in Flex
+ *
+ * @param classes - Array to push classes into
+ * @param value - Static value or responsive object
+ * @param classMap - Map of value to class name
+ * @param mode - "screen" (default) or "container"
+ */
+export declare const pushResponsiveClasses: <T extends string | number>(classes: string[], value: LayoutResponsiveValue<T> | undefined, classMap: Record<T, string>, mode?: ResponsiveMode) => void;