@askrjs/themes 0.0.1

package/src/components/_internal/layout.ts

@@ -0,0 +1,223 @@
+/**
+ * Layout helpers shared by headless layout primitives.
+ */
+
+export type LayoutBreakpoint = "initial" | "sm" | "md" | "lg" | "xl";
+export type ResponsiveValue<T> = T | Partial<Record<LayoutBreakpoint, T>>;
+
+const BREAKPOINTS: readonly LayoutBreakpoint[] = ["initial", "sm", "md", "lg", "xl"];
+
+/** Units and patterns that identify a concrete CSS length value. */
+const CSS_UNIT_RE =
+  /^-?[\d.]+(%|px|em|rem|ex|ch|ic|lh|rlh|vw|vh|vmin|vmax|svw|svh|dvw|dvh|cqw|cqh|cqi|cqb|fr|cm|mm|in|pt|pc|Q)$/;
+
+const SPACE_TOKEN_MAP: Record<string, string> = {
+  "1": "var(--ak-space-1)",
+  "2": "var(--ak-space-2)",
+  "3": "var(--ak-space-3)",
+  "4": "var(--ak-space-4)",
+  "5": "var(--ak-space-5)",
+  "6": "var(--ak-space-6)",
+  "7": "var(--ak-space-7)",
+  "8": "var(--ak-space-8)",
+  "9": "var(--ak-space-9)",
+  xs: "var(--ak-space-xs)",
+  sm: "var(--ak-space-sm)",
+  md: "var(--ak-space-md)",
+  lg: "var(--ak-space-lg)",
+  xl: "var(--ak-space-xl)",
+  "2xl": "var(--ak-space-2xl)",
+  "3xl": "var(--ak-space-3xl)",
+};
+
+const CONTAINER_SIZE_MAP: Record<string, string> = {
+  "1": "var(--ak-container-1)",
+  "2": "var(--ak-container-2)",
+  "3": "var(--ak-container-3)",
+  "4": "var(--ak-container-4)",
+  sm: "var(--ak-container-1)",
+  md: "var(--ak-container-2)",
+  lg: "var(--ak-container-3)",
+  xl: "var(--ak-container-4)",
+};
+
+const SECTION_SIZE_MAP: Record<string, string> = {
+  "1": "var(--ak-section-1)",
+  "2": "var(--ak-section-2)",
+  "3": "var(--ak-section-3)",
+  "4": "var(--ak-section-4)",
+};
+
+/**
+ * Returns true when `value` is a concrete CSS length/size that can be applied
+ * directly as an inline style.
+ */
+export function isCssLength(value: unknown): value is string {
+  if (typeof value !== "string") return false;
+  const v = value.trim();
+  if (v === "0") return true;
+  if (CSS_UNIT_RE.test(v)) return true;
+  // CSS functions: calc(), min(), max(), clamp(), fit-content(), env(), var()
+  if (/^[a-z][a-z-]*\(/.test(v)) return true;
+  return false;
+}
+
+export function isResponsiveValue<T>(
+  value: ResponsiveValue<T> | undefined,
+): value is Partial<Record<LayoutBreakpoint, T>> {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return false;
+  return BREAKPOINTS.some((breakpoint) => breakpoint in value);
+}
+
+export function normalizeResponsiveValue<T>(
+  value: ResponsiveValue<T> | undefined,
+): Partial<Record<LayoutBreakpoint, T>> | undefined {
+  if (value === undefined) return undefined;
+  if (isResponsiveValue(value)) return value;
+  return { initial: value };
+}
+
+export function serializeResponsiveValue<T>(
+  value: ResponsiveValue<T> | undefined,
+): string | undefined {
+  const normalized = normalizeResponsiveValue(value);
+  if (!normalized) return undefined;
+
+  return BREAKPOINTS.map((breakpoint) => {
+    const breakpointValue = normalized[breakpoint];
+    if (breakpointValue === undefined) return "";
+    return `${breakpoint}:${String(breakpointValue)}`;
+  })
+    .filter(Boolean)
+    .join("|");
+}
+
+export function serializeResponsiveValueIf<T>(
+  value: ResponsiveValue<T> | undefined,
+  predicate: (value: T) => boolean,
+): string | undefined {
+  const normalized = normalizeResponsiveValue(value);
+  if (!normalized) return undefined;
+
+  for (const breakpoint of BREAKPOINTS) {
+    const breakpointValue = normalized[breakpoint];
+    if (breakpointValue === undefined) continue;
+    if (!predicate(breakpointValue)) return undefined;
+  }
+
+  return serializeResponsiveValue(value);
+}
+
+export function serializeValueIf<T>(
+  value: T | undefined,
+  predicate: (value: T) => boolean,
+): string | undefined {
+  if (value === undefined || !predicate(value)) return undefined;
+  return String(value);
+}
+
+export function setResponsiveStyleVar<T>(
+  styles: Record<string, string | number>,
+  variable: string,
+  value: ResponsiveValue<T> | undefined,
+  resolve: (value: T) => string | number | undefined = (input) =>
+    input as string | number | undefined,
+) {
+  const normalized = normalizeResponsiveValue(value);
+  if (!normalized) return;
+
+  for (const breakpoint of BREAKPOINTS) {
+    const breakpointValue = normalized[breakpoint];
+    if (breakpointValue === undefined) continue;
+    const resolved = resolve(breakpointValue);
+    if (resolved === undefined || resolved === null || resolved === "") continue;
+    styles[`--ak-${variable}-${breakpoint}`] = resolved;
+  }
+}
+
+export function resolveSpaceValue(value: string | number): string | number {
+  if (typeof value === "number") return String(value);
+  const trimmed = value.trim();
+  return SPACE_TOKEN_MAP[trimmed] ?? trimmed;
+}
+
+export function resolveContainerSizeValue(value: string): string {
+  const trimmed = value.trim();
+  return CONTAINER_SIZE_MAP[trimmed] ?? trimmed;
+}
+
+export function resolveSectionSizeValue(value: string): string {
+  const trimmed = value.trim();
+  return SECTION_SIZE_MAP[trimmed] ?? trimmed;
+}
+
+export function resolveGridTrackValue(value: string | number): string {
+  if (typeof value === "number") {
+    return `repeat(${value}, minmax(0, 1fr))`;
+  }
+
+  const trimmed = value.trim();
+  if (/^\d+$/.test(trimmed)) {
+    return `repeat(${trimmed}, minmax(0, 1fr))`;
+  }
+
+  return trimmed;
+}
+
+export function resolveJustifyValue(value: string): string {
+  const trimmed = value.trim();
+  if (trimmed === "between") return "space-between";
+  if (trimmed === "start") return "flex-start";
+  if (trimmed === "end") return "flex-end";
+  return trimmed;
+}
+
+export function resolveAlignValue(value: string): string {
+  const trimmed = value.trim();
+  if (trimmed === "start") return "flex-start";
+  if (trimmed === "end") return "flex-end";
+  return trimmed;
+}
+
+export function resolveInlineAlignValue(value: "left" | "center" | "right"): {
+  marginLeft?: string;
+  marginRight?: string;
+} {
+  if (value === "left") return { marginLeft: "0", marginRight: "auto" };
+  if (value === "right") return { marginLeft: "auto", marginRight: "0" };
+  return { marginLeft: "auto", marginRight: "auto" };
+}
+
+/**
+ * Merges a record of computed layout styles with a user-supplied `style` prop.
+ * The user's styles take precedence for conflicting keys.
+ */
+export function mergeLayoutStyles(
+  layout: Record<string, string | number>,
+  user: unknown,
+): string | undefined {
+  const merged: Record<string, unknown> = { ...layout };
+
+  if (user !== null && user !== undefined && typeof user === "object") {
+    Object.assign(merged, user as Record<string, unknown>);
+  }
+
+  const mergedString = objectToCssString(merged);
+
+  if (typeof user === "string" && user.trim()) {
+    return mergedString ? `${mergedString};${user.trim()}` : user.trim();
+  }
+
+  return mergedString || undefined;
+}
+
+function camelToKebab(s: string): string {
+  return s.replace(/([A-Z])/g, (c) => `-${c.toLowerCase()}`);
+}
+
+function objectToCssString(styles: Record<string, unknown>): string {
+  return Object.entries(styles)
+    .filter(([, value]) => value !== undefined && value !== null)
+    .map(([key, value]) => `${camelToKebab(key)}:${String(value)}`)
+    .join(";");
+}

package/src/components/_internal/merge-props.ts

@@ -0,0 +1,89 @@
+type Handler = (...args: readonly unknown[]) => void;
+type Ref<T> = { current: T | null } | ((value: T | null) => void) | null | undefined;
+
+function isEventHandlerKey(key: string): boolean {
+  return key.startsWith("on");
+}
+
+function isDefaultPrevented(value: unknown): value is { defaultPrevented: true } {
+  return (
+    typeof value === "object" &&
+    value !== null &&
+    "defaultPrevented" in value &&
+    (value as { defaultPrevented?: boolean }).defaultPrevented === true
+  );
+}
+
+function composeHandlers(first: Handler, second: Handler): Handler {
+  return (...args) => {
+    first(...args);
+
+    if (isDefaultPrevented(args[0])) {
+      return;
+    }
+
+    second(...args);
+  };
+}
+
+function setRef<T>(ref: Ref<T>, value: T | null): void {
+  if (!ref) return;
+
+  if (typeof ref === "function") {
+    ref(value);
+    return;
+  }
+
+  if (Object.isExtensible(ref)) {
+    (ref as { current: T | null }).current = value;
+  }
+}
+
+function composeRefs<T>(...refs: Array<Ref<T>>): (value: T | null) => void {
+  return (value: T | null) => {
+    for (const ref of refs) {
+      setRef(ref, value);
+    }
+  };
+}
+
+export function mergeProps<TBase extends object, TInjected extends object>(
+  base: TBase,
+  injected: TInjected,
+): TInjected & TBase {
+  const baseKeys = Object.keys(base);
+  if (baseKeys.length === 0) {
+    return injected as TInjected & TBase;
+  }
+
+  const out = { ...(injected as object) } as TInjected & TBase;
+
+  for (const key of baseKeys as Array<Extract<keyof TBase, string>>) {
+    const baseValue = (base as Record<string, unknown>)[key];
+    const injectedValue = (injected as Record<string, unknown>)[key];
+
+    if (key === "ref") {
+      (out as Record<string, unknown>)[key] = composeRefs(
+        injectedValue as Ref<unknown>,
+        baseValue as Ref<unknown>,
+      );
+      continue;
+    }
+
+    if (
+      isEventHandlerKey(key) &&
+      typeof baseValue === "function" &&
+      typeof injectedValue === "function"
+    ) {
+      (out as Record<string, unknown>)[key] = composeHandlers(
+        injectedValue as Handler,
+        baseValue as Handler,
+      );
+      continue;
+    }
+
+    (out as Record<string, unknown>)[key] = baseValue;
+  }
+
+  return out;
+}

package/src/components/_internal/style.ts

@@ -0,0 +1,18 @@
+export function mergeCssVar(style: unknown, name: string, value: string): string {
+  const decl = `${name}:${value}`;
+
+  if (typeof style === "string") {
+    const trimmed = style.trim();
+    return trimmed ? `${trimmed};${decl}` : decl;
+  }
+
+  if (style && typeof style === "object") {
+    const entries = Object.entries(style as Record<string, unknown>)
+      .filter(([, v]) => v !== undefined && v !== null)
+      .map(([k, v]) => `${k.replace(/([A-Z])/g, (c) => `-${c.toLowerCase()}`)}:${String(v)}`)
+      .join(";");
+    return entries ? `${entries};${decl}` : decl;
+  }
+
+  return decl;
+}

package/src/components/accessible-icon/accessible-icon.tsx

@@ -0,0 +1,18 @@
+import type { AccessibleIconProps } from "./accessible-icon.types";
+
+export function AccessibleIcon(props: AccessibleIconProps): JSX.Element {
+  const { children, label, decorative = label ? false : true } = props;
+
+  return (
+    <span
+      data-slot="accessible-icon"
+      data-decorative={decorative ? "true" : undefined}
+      role={decorative ? undefined : "img"}
+      aria-hidden={decorative ? "true" : undefined}
+      aria-label={decorative ? undefined : label}
+    >
+      {children}
+      {!decorative && label ? <span class="sr-only">{label}</span> : null}
+    </span>
+  );
+}

package/src/components/accessible-icon/accessible-icon.types.ts

@@ -0,0 +1,5 @@
+export type AccessibleIconProps = {
+  children?: unknown;
+  label?: string;
+  decorative?: boolean;
+};

package/src/components/accessible-icon/index.ts

@@ -0,0 +1,2 @@
+export { AccessibleIcon } from "./accessible-icon";
+export type { AccessibleIconProps } from "./accessible-icon.types";

package/src/components/aspect-ratio/aspect-ratio.tsx

@@ -0,0 +1,48 @@
+import { Slot } from "@askrjs/askr/foundations";
+import { mergeProps } from "../_internal/merge-props";
+import type { AspectRatioAsChildProps, AspectRatioProps } from "./aspect-ratio.types";
+
+function serializeStyle(base: Record<string, string | number>, user: unknown): string {
+  const merged: Record<string, unknown> = { ...base };
+
+  if (user && typeof user === "object") {
+    Object.assign(merged, user as Record<string, unknown>);
+  }
+
+  if (typeof user === "string" && user.trim()) {
+    return `${Object.entries(merged)
+      .filter(([, value]) => value !== undefined && value !== null)
+      .map(([key, value]) => key.replace(/([A-Z])/g, "-$1").toLowerCase() + ":" + String(value))
+      .join(";")};${user.trim()}`;
+  }
+
+  return Object.entries(merged)
+    .filter(([, value]) => value !== undefined && value !== null)
+    .map(([key, value]) => key.replace(/([A-Z])/g, "-$1").toLowerCase() + ":" + String(value))
+    .join(";");
+}
+
+export function AspectRatio(props: AspectRatioProps): JSX.Element;
+export function AspectRatio(props: AspectRatioAsChildProps): JSX.Element;
+export function AspectRatio(props: AspectRatioProps | AspectRatioAsChildProps) {
+  const { asChild, children, ratio = 1, ref, style, ...rest } = props;
+  const finalProps = mergeProps(rest, {
+    ref,
+    "data-slot": "aspect-ratio",
+    style: serializeStyle(
+      {
+        display: "block",
+        width: "100%",
+        aspectRatio: String(ratio),
+        overflow: "hidden",
+      },
+      style,
+    ),
+  });
+
+  if (asChild) {
+    return <Slot asChild {...finalProps} children={children} />;
+  }
+
+  return <div {...finalProps}>{children}</div>;
+}

package/src/components/aspect-ratio/aspect-ratio.types.ts

@@ -0,0 +1,19 @@
+import type { JSXElement, Ref } from "@askrjs/askr/foundations";
+
+export type AspectRatioOwnProps = {
+  children?: unknown;
+  ratio?: number | string;
+  style?: unknown;
+};
+
+export type AspectRatioProps = Omit<JSX.IntrinsicElements["div"], "children" | "ref"> &
+  AspectRatioOwnProps & {
+    asChild?: false;
+    ref?: Ref<HTMLDivElement>;
+  };
+
+export type AspectRatioAsChildProps = AspectRatioOwnProps & {
+  asChild: true;
+  children: JSXElement;
+  ref?: Ref<unknown>;
+};

package/src/components/aspect-ratio/index.ts

@@ -0,0 +1,2 @@
+export { AspectRatio } from "./aspect-ratio";
+export type { AspectRatioAsChildProps, AspectRatioProps } from "./aspect-ratio.types";

package/src/components/badge/badge.a11y.ts

@@ -0,0 +1,15 @@
+/**
+ * Accessibility contract for Badge.
+ */
+
+export const BADGE_A11Y_CONTRACT = {
+  DATA_ATTRIBUTES: {
+    slot: "data-slot" as const,
+  },
+  MARKER: "data-badge" as const,
+  CONTENT: {
+    textAllowed: true,
+  },
+} as const;
+
+export type BadgeA11yContract = typeof BADGE_A11Y_CONTRACT;

package/src/components/badge/badge.tsx

@@ -0,0 +1,21 @@
+import { Slot } from "@askrjs/askr/foundations";
+import { mergeProps } from "../_internal/merge-props";
+import type { BadgeAsChildProps, BadgeProps } from "./badge.types";
+
+export function Badge(props: BadgeProps): JSX.Element;
+export function Badge(props: BadgeAsChildProps): JSX.Element;
+export function Badge(props: BadgeProps | BadgeAsChildProps) {
+  const { asChild, children, variant, ref, ...rest } = props;
+  const finalProps = mergeProps(rest, {
+    ref,
+    "data-slot": "badge",
+    "data-badge": "true",
+    "data-variant": variant && variant !== "default" ? variant : undefined,
+  });
+
+  if (asChild) {
+    return <Slot asChild {...finalProps} children={children} />;
+  }
+
+  return <span {...finalProps}>{children}</span>;
+}

package/src/components/badge/badge.types.ts

@@ -0,0 +1,27 @@
+import type { JSXElement, Ref } from "@askrjs/askr/foundations";
+
+export type BadgeVariant =
+  | "default"
+  | "secondary"
+  | "outline"
+  | "success"
+  | "warning"
+  | "danger"
+  | "info";
+
+export type BadgeOwnProps = {
+  children?: unknown;
+  variant?: BadgeVariant;
+};
+
+export type BadgeProps = Omit<JSX.IntrinsicElements["span"], "children" | "ref"> &
+  BadgeOwnProps & {
+    asChild?: false;
+    ref?: Ref<HTMLSpanElement>;
+  };
+
+export type BadgeAsChildProps = BadgeOwnProps & {
+  asChild: true;
+  children: JSXElement;
+  ref?: Ref<unknown>;
+};

package/src/components/badge/index.ts

@@ -0,0 +1,3 @@
+export { Badge } from "./badge";
+export { BADGE_A11Y_CONTRACT, type BadgeA11yContract } from "./badge.a11y";
+export type { BadgeOwnProps, BadgeProps, BadgeAsChildProps } from "./badge.types";

package/src/components/box/box.a11y.ts

@@ -0,0 +1,11 @@
+export const BOX_A11Y_CONTRACT = {
+  DATA_ATTRIBUTES: {
+    slot: "data-slot" as const,
+    layout: "data-ak-layout" as const,
+  },
+  SLOT_VALUES: {
+    root: "box" as const,
+  },
+} as const;
+
+export type BoxA11yContract = typeof BOX_A11Y_CONTRACT;

package/src/components/box/box.tsx

@@ -0,0 +1,37 @@
+import { Slot } from "@askrjs/askr/foundations";
+import { mergeProps } from "../_internal/merge-props";
+import {
+  applyBoxLayoutStyles,
+  splitBoxLayoutProps,
+  withBoxLayoutStyle,
+} from "../_internal/box-layout";
+import type { BoxAsChildProps, BoxDivProps, BoxSpanProps } from "./box.types";
+
+export function Box(props: BoxDivProps): JSX.Element;
+export function Box(props: BoxSpanProps): JSX.Element;
+export function Box(props: BoxAsChildProps): JSX.Element;
+export function Box(props: BoxDivProps | BoxSpanProps | BoxAsChildProps) {
+  const as = "as" in props ? props.as : "div";
+  const { asChild, children, ref, style: userStyle, ...rest } = props;
+
+  const { boxProps, rest: passthroughProps } = splitBoxLayoutProps(rest);
+  const layoutStyle: Record<string, string | number> = {};
+  applyBoxLayoutStyles(layoutStyle, boxProps);
+
+  const finalProps = mergeProps(passthroughProps, {
+    ref,
+    "data-slot": "box",
+    "data-ak-layout": "true",
+    style: withBoxLayoutStyle(layoutStyle, userStyle),
+  });
+
+  if (asChild) {
+    return <Slot asChild {...finalProps} children={children} />;
+  }
+
+  if (as === "span") {
+    return <span {...finalProps}>{children}</span>;
+  }
+
+  return <div {...finalProps}>{children}</div>;
+}

package/src/components/box/box.types.ts

@@ -0,0 +1,75 @@
+import type { JSXElement, Ref } from "@askrjs/askr/foundations";
+import type { ResponsiveValue } from "../_internal/layout";
+
+export type LayoutResponsive<T> = ResponsiveValue<T>;
+
+export type BoxLayoutOwnProps = {
+  display?: ResponsiveValue<string>;
+  m?: ResponsiveValue<string | number>;
+  mx?: ResponsiveValue<string | number>;
+  my?: ResponsiveValue<string | number>;
+  mt?: ResponsiveValue<string | number>;
+  mr?: ResponsiveValue<string | number>;
+  mb?: ResponsiveValue<string | number>;
+  ml?: ResponsiveValue<string | number>;
+  p?: ResponsiveValue<string | number>;
+  px?: ResponsiveValue<string | number>;
+  py?: ResponsiveValue<string | number>;
+  pt?: ResponsiveValue<string | number>;
+  pr?: ResponsiveValue<string | number>;
+  pb?: ResponsiveValue<string | number>;
+  pl?: ResponsiveValue<string | number>;
+  width?: ResponsiveValue<string>;
+  minWidth?: ResponsiveValue<string>;
+  maxWidth?: ResponsiveValue<string>;
+  height?: ResponsiveValue<string>;
+  minHeight?: ResponsiveValue<string>;
+  maxHeight?: ResponsiveValue<string>;
+  position?: ResponsiveValue<string>;
+  inset?: ResponsiveValue<string | number>;
+  top?: ResponsiveValue<string | number>;
+  right?: ResponsiveValue<string | number>;
+  bottom?: ResponsiveValue<string | number>;
+  left?: ResponsiveValue<string | number>;
+  overflow?: ResponsiveValue<string>;
+  overflowX?: ResponsiveValue<string>;
+  overflowY?: ResponsiveValue<string>;
+  flexBasis?: ResponsiveValue<string>;
+  flexGrow?: ResponsiveValue<string | number>;
+  flexShrink?: ResponsiveValue<string | number>;
+  gridArea?: ResponsiveValue<string>;
+  gridColumn?: ResponsiveValue<string>;
+  gridColumnStart?: ResponsiveValue<string>;
+  gridColumnEnd?: ResponsiveValue<string>;
+  gridRow?: ResponsiveValue<string>;
+  gridRowStart?: ResponsiveValue<string>;
+  gridRowEnd?: ResponsiveValue<string>;
+  children?: unknown;
+};
+
+export type BoxOwnProps = BoxLayoutOwnProps & {
+  as?: "div" | "span";
+};
+
+export type BoxDivProps = Omit<JSX.IntrinsicElements["div"], "children" | "ref"> &
+  BoxOwnProps & {
+    as?: "div";
+    asChild?: false;
+    ref?: Ref<HTMLDivElement>;
+  };
+
+export type BoxSpanProps = Omit<JSX.IntrinsicElements["span"], "children" | "ref"> &
+  BoxOwnProps & {
+    as: "span";
+    asChild?: false;
+    ref?: Ref<HTMLSpanElement>;
+  };
+
+export type BoxAsChildProps = Omit<BoxOwnProps, "as"> & {
+  asChild: true;
+  children: JSXElement;
+  ref?: Ref<unknown>;
+  style?: JSX.IntrinsicElements["div"]["style"];
+};
+
+export type BoxProps = BoxDivProps | BoxSpanProps | BoxAsChildProps;

package/src/components/box/index.ts

@@ -0,0 +1,11 @@
+export { Box } from "./box";
+export { BOX_A11Y_CONTRACT, type BoxA11yContract } from "./box.a11y";
+export type {
+  BoxProps,
+  BoxOwnProps,
+  BoxLayoutOwnProps,
+  BoxDivProps,
+  BoxSpanProps,
+  BoxAsChildProps,
+  LayoutResponsive,
+} from "./box.types";

package/src/components/breadcrumb/breadcrumb.a11y.ts

@@ -0,0 +1,15 @@
+/**
+ * Breadcrumb accessibility contract.
+ */
+
+export const BREADCRUMB_A11Y_CONTRACT = {
+  DATA_ATTRIBUTES: {
+    slot: "data-slot" as const,
+  },
+  NAV_ROLE: "navigation" as const,
+  CURRENT_PAGE_ATTRIBUTE: "aria-current" as const,
+  CURRENT_PAGE_VALUE: "page" as const,
+  SEPARATOR_MARKER: "data-breadcrumb-separator" as const,
+} as const;
+
+export type BreadcrumbA11yContract = typeof BREADCRUMB_A11Y_CONTRACT;