@hraness/design-kit 0.31.1

package/src/react/surfaces.tsx

@@ -0,0 +1,330 @@
+import type {
+  HTMLAttributes,
+  ReactNode,
+} from "react";
+import { forwardRef } from "react";
+import * as stylex from "@stylexjs/stylex";
+
+import { ThemedSurface, cn, type ThemedSurfaceProps } from "@hraness/ui";
+
+import {
+  ditherSurfaceStyles,
+  layoutSurfaceStyles,
+} from "./surfaces.stylex.js";
+
+export type DitherSurfaceDensity = "coarse" | "fine" | "medium";
+
+export interface DitherSurfaceProps extends ThemedSurfaceProps {
+  readonly density?: DitherSurfaceDensity;
+}
+
+const ditherSurfaceDensityStyles = {
+  coarse: ditherSurfaceStyles.coarse,
+  fine: ditherSurfaceStyles.fine,
+  medium: undefined,
+} as const satisfies Readonly<Record<DitherSurfaceDensity, unknown>>;
+
+export function DitherSurface({
+  className,
+  density = "medium",
+  xstyle,
+  ...props
+}: DitherSurfaceProps) {
+  return (
+    <ThemedSurface
+      {...props}
+      className={cn("hraness-design-dither-surface", className)}
+      data-density={density}
+      xstyle={[
+        ditherSurfaceStyles.texture,
+        // The public ThemedSurface seam intentionally types standard CSS
+        // properties. StyleX still extracts this package-owned literal custom
+        // property, so keep the narrow cast at the composition boundary.
+        ditherSurfaceDensityStyles[density] as ThemedSurfaceProps["xstyle"],
+        xstyle,
+      ]}
+    />
+  );
+}
+
+export interface TopBarProps extends Omit<HTMLAttributes<HTMLElement>, "title"> {
+  readonly actions?: ReactNode;
+  readonly leading?: ReactNode;
+  readonly position?: "static" | "sticky";
+  readonly surface?: "glass" | "solid";
+  readonly title?: ReactNode;
+}
+
+export function TopBar({
+  actions,
+  children,
+  className,
+  leading,
+  position = "static",
+  surface = "solid",
+  title,
+  ...props
+}: TopBarProps) {
+  const rootPresentation = stylex.props(
+    layoutSurfaceStyles.surface,
+    layoutSurfaceStyles.bar,
+    layoutSurfaceStyles.topBar,
+    position === "sticky"
+      ? layoutSurfaceStyles.topBarSticky
+      : layoutSurfaceStyles.topBarStatic,
+    surface === "glass" && layoutSurfaceStyles.topBarGlass,
+  );
+  const leadingPresentation = stylex.props(layoutSurfaceStyles.barPart);
+  const titlePresentation = stylex.props(layoutSurfaceStyles.topBarTitle);
+  const contentPresentation = stylex.props(
+    layoutSurfaceStyles.barPart,
+    layoutSurfaceStyles.barContent,
+  );
+  const actionsPresentation = stylex.props(
+    layoutSurfaceStyles.barPart,
+    layoutSurfaceStyles.topBarActions,
+  );
+
+  return (
+    <header
+      {...rootPresentation}
+      {...props}
+      className={cn(
+        "hraness-design-top-bar",
+        rootPresentation.className,
+        className,
+      )}
+      data-position={position}
+      data-surface={surface}
+    >
+      <div
+        {...leadingPresentation}
+        className={cn(
+          "hraness-design-top-bar__leading",
+          leadingPresentation.className,
+        )}
+      >
+        {leading}
+        {title === undefined
+          ? null
+          : (
+              <div
+                {...titlePresentation}
+                className={cn(
+                  "hraness-design-top-bar__title",
+                  titlePresentation.className,
+                )}
+              >
+                {title}
+              </div>
+            )}
+      </div>
+      {children === undefined
+        ? null
+        : (
+            <div
+              {...contentPresentation}
+              className={cn(
+                "hraness-design-top-bar__content",
+                contentPresentation.className,
+              )}
+            >
+              {children}
+            </div>
+          )}
+      {actions === undefined
+        ? null
+        : (
+            <div
+              {...actionsPresentation}
+              className={cn(
+                "hraness-design-top-bar__actions",
+                actionsPresentation.className,
+              )}
+            >
+              {actions}
+            </div>
+          )}
+    </header>
+  );
+}
+
+export interface BottomBarProps extends HTMLAttributes<HTMLElement> {
+  readonly actions?: ReactNode;
+  readonly leading?: ReactNode;
+}
+
+export function BottomBar({ actions, children, className, leading, ...props }: BottomBarProps) {
+  const rootPresentation = stylex.props(
+    layoutSurfaceStyles.surface,
+    layoutSurfaceStyles.bar,
+    layoutSurfaceStyles.bottomBar,
+  );
+  const leadingPresentation = stylex.props(layoutSurfaceStyles.barPart);
+  const contentPresentation = stylex.props(
+    layoutSurfaceStyles.barPart,
+    layoutSurfaceStyles.barContent,
+  );
+  const actionsPresentation = stylex.props(layoutSurfaceStyles.barPart);
+
+  return (
+    <footer
+      {...rootPresentation}
+      {...props}
+      className={cn(
+        "hraness-design-bottom-bar",
+        rootPresentation.className,
+        className,
+      )}
+    >
+      {leading === undefined
+        ? null
+        : (
+            <div
+              {...leadingPresentation}
+              className={cn(
+                "hraness-design-bottom-bar__leading",
+                leadingPresentation.className,
+              )}
+            >
+              {leading}
+            </div>
+          )}
+      <div
+        {...contentPresentation}
+        className={cn(
+          "hraness-design-bottom-bar__content",
+          contentPresentation.className,
+        )}
+      >
+        {children}
+      </div>
+      {actions === undefined
+        ? null
+        : (
+            <div
+              {...actionsPresentation}
+              className={cn(
+                "hraness-design-bottom-bar__actions",
+                actionsPresentation.className,
+              )}
+            >
+              {actions}
+            </div>
+          )}
+    </footer>
+  );
+}
+
+export interface PageCanvasProps extends HTMLAttributes<HTMLElement> {
+  readonly as?: "div" | "main";
+  readonly inset?: "content" | "none";
+  readonly size?: "default" | "full" | "wide";
+}
+
+export function PageCanvas({
+  as = "main",
+  className,
+  inset = "content",
+  size = "default",
+  ...props
+}: PageCanvasProps) {
+  const Element = as;
+  const presentation = stylex.props(
+    layoutSurfaceStyles.pageCanvas,
+    inset === "content"
+      ? layoutSurfaceStyles.pageContentInset
+      : layoutSurfaceStyles.pageNoInset,
+    size === "wide" && layoutSurfaceStyles.wideSize,
+    size === "full" && layoutSurfaceStyles.fullSize,
+  );
+
+  return (
+    <Element
+      {...presentation}
+      {...props}
+      className={cn(
+        "hraness-design-page-canvas",
+        presentation.className,
+        className,
+      )}
+      data-inset={inset}
+      data-size={size}
+    />
+  );
+}
+
+export interface DockedFooterProps extends HTMLAttributes<HTMLElement> {
+  readonly contentClassName?: string;
+  readonly density?: "compact" | "default";
+  readonly inset?: "content" | "none";
+  readonly position?: "absolute" | "fixed" | "sticky";
+  readonly size?: "default" | "full" | "wide";
+  readonly surface?: "glass" | "solid";
+}
+
+export const DockedFooter = forwardRef<HTMLElement, DockedFooterProps>(function DockedFooter(
+  {
+    children,
+    className,
+    contentClassName,
+    density = "default",
+    inset = "content",
+    position = "fixed",
+    size = "default",
+    surface = "solid",
+    ...props
+  },
+  ref,
+) {
+  const rootPresentation = stylex.props(
+    layoutSurfaceStyles.surface,
+    layoutSurfaceStyles.dockedFooter,
+    position === "absolute"
+      ? layoutSurfaceStyles.dockedAbsolute
+      : position === "sticky"
+        ? layoutSurfaceStyles.dockedSticky
+        : layoutSurfaceStyles.dockedFixed,
+  );
+  const contentPresentation = stylex.props(
+    layoutSurfaceStyles.dockedContent,
+    density === "compact"
+      ? inset === "content"
+        ? layoutSurfaceStyles.dockedContentCompactInset
+        : layoutSurfaceStyles.dockedContentCompactNoInset
+      : inset === "content"
+        ? layoutSurfaceStyles.dockedContentDefaultInset
+        : layoutSurfaceStyles.dockedContentDefaultNoInset,
+    size === "wide" && layoutSurfaceStyles.wideSize,
+    size === "full" && layoutSurfaceStyles.fullSize,
+  );
+
+  return (
+    <footer
+      {...rootPresentation}
+      {...props}
+      className={cn(
+        "hraness-design-docked-footer",
+        rootPresentation.className,
+        className,
+      )}
+      data-position={position}
+      data-surface={surface}
+      ref={ref}
+    >
+      <div
+        {...contentPresentation}
+        className={cn(
+          "hraness-design-docked-footer__content",
+          contentPresentation.className,
+          contentClassName,
+        )}
+        data-density={density}
+        data-inset={inset}
+        data-size={size}
+      >
+        {children}
+      </div>
+    </footer>
+  );
+});

package/src/react/syntax-code.tsx

@@ -0,0 +1,33 @@
+import {
+  highlightCode,
+  type HighlightCodeOptions,
+} from "../syntax-highlighting.js";
+
+export interface SyntaxCodeProps {
+  readonly className?: string;
+  readonly code: string;
+  /** A language/fence hint; omitted hints use conservative automatic selection. */
+  readonly language?: string;
+  readonly styles?: HighlightCodeOptions["styles"];
+}
+
+/** Server-rendered syntax markup with no client runtime or hydration cost. */
+export function SyntaxCode({
+  className,
+  code,
+  language,
+  styles,
+}: SyntaxCodeProps) {
+  const highlighted = highlightCode(code, language, styles === undefined ? {} : { styles });
+  const classes = className === undefined
+    ? highlighted.className
+    : `${highlighted.className} ${className}`;
+
+  return (
+    <code
+      className={classes}
+      data-language={highlighted.language}
+      dangerouslySetInnerHTML={{ __html: highlighted.html }}
+    />
+  );
+}

package/src/react/theme-color-sync.ts

@@ -0,0 +1 @@
+export * from "../browser/theme-color-sync.js";

package/src/react/theme-resolution.ts

@@ -0,0 +1,11 @@
+import type { ConcreteDesignTheme } from "../appearance.js";
+
+/** next-themes keeps the saved/resolved preference separate from a forced mode. */
+export function resolveEffectiveTheme(
+  forcedTheme: unknown,
+  resolvedTheme: unknown,
+): ConcreteDesignTheme | undefined {
+  if (forcedTheme === "light" || forcedTheme === "dark") return forcedTheme;
+  if (resolvedTheme === "light" || resolvedTheme === "dark") return resolvedTheme;
+  return undefined;
+}

package/src/react/theme.stylex.ts

@@ -0,0 +1,276 @@
+import * as stylex from "@stylexjs/stylex";
+
+const coarsePointer = "@media (pointer: coarse)";
+const forcedColors = "@media (forced-colors: active)";
+const reducedMotion = "@media (prefers-reduced-motion: reduce)";
+const disabled = ":disabled";
+const focusVisible = ":is([data-focus-visible], :focus-visible)";
+const hidden = ":is([hidden])";
+const hovered = ":is([data-hovered], :hover)";
+const itemFocusedOrHovered =
+  ":is([data-focused], [data-hovered], :focus-visible, :hover)";
+const pressed = ":is([data-pressed], :active)";
+
+// The popover is portalled outside the menu root, so its paint reads the
+// inherited Lantern tokens directly after any caller-set appearance variable.
+const lanternAccent =
+  "var(--hraness-material-warm-plane, var(--ui-accent, ButtonFace))";
+const lanternAccentForeground =
+  "var(--hraness-material-ink, var(--ui-accent-foreground, ButtonText))";
+const lanternPopoverBackground =
+  "var(--hraness-material-plane, var(--ui-popover, Canvas))";
+const lanternPopoverForeground =
+  "var(--hraness-material-ink, var(--ui-popover-foreground, CanvasText))";
+const accent = `var(--hraness-appearance-accent, ${lanternAccent})`;
+const accentForeground =
+  `var(--hraness-appearance-accent-foreground, ${lanternAccentForeground})`;
+const popoverForeground =
+  `var(--hraness-appearance-popover-foreground, ${lanternPopoverForeground})`;
+const controlBorder =
+  "var(--hraness-appearance-control-border, var(--hraness-material-seam, var(--ui-input, GrayText)))";
+
+export const themeStyles = stylex.create({
+  item: {
+    alignItems: "center",
+    backgroundAttachment: { default: null, [itemFocusedOrHovered]: "scroll" },
+    backgroundClip: { default: null, [itemFocusedOrHovered]: "border-box" },
+    backgroundImage: { default: null, [itemFocusedOrHovered]: "none" },
+    backgroundOrigin: { default: null, [itemFocusedOrHovered]: "padding-box" },
+    backgroundPosition: { default: null, [itemFocusedOrHovered]: "0% 0%" },
+    backgroundRepeat: { default: null, [itemFocusedOrHovered]: "repeat" },
+    backgroundSize: { default: null, [itemFocusedOrHovered]: "auto auto" },
+    backgroundColor: {
+      default: null,
+      [itemFocusedOrHovered]: accent,
+    },
+    borderRadius: "var(--radius-md, 0.5rem)",
+    color: {
+      default: popoverForeground,
+      [itemFocusedOrHovered]: accentForeground,
+    },
+    cursor: "default",
+    display: "grid",
+    fontSize: "var(--text-label, 0.875rem)",
+    gap: "0.75rem",
+    gridTemplateColumns: "auto minmax(0, 1fr)",
+    lineHeight: 1.25,
+    "min-block-size": {
+      default: "2.5rem",
+      [coarsePointer]: "3rem",
+    },
+    outlineStyle: "none",
+    paddingBlock: "0.5rem",
+    paddingInline: "0.75rem",
+    userSelect: "none",
+  },
+  itemSelected: {
+    backgroundAttachment: { default: null, [itemFocusedOrHovered]: "scroll", [forcedColors]: "scroll" },
+    backgroundClip: { default: null, [itemFocusedOrHovered]: "border-box", [forcedColors]: "border-box" },
+    backgroundImage: { default: null, [itemFocusedOrHovered]: "none", [forcedColors]: "none" },
+    backgroundOrigin: { default: null, [itemFocusedOrHovered]: "padding-box", [forcedColors]: "padding-box" },
+    backgroundPosition: { default: null, [itemFocusedOrHovered]: "0% 0%", [forcedColors]: "0% 0%" },
+    backgroundRepeat: { default: null, [itemFocusedOrHovered]: "repeat", [forcedColors]: "repeat" },
+    backgroundSize: { default: null, [itemFocusedOrHovered]: "auto auto", [forcedColors]: "auto auto" },
+    // Lantern marks the selected appearance with its warm plane at rest.
+    backgroundColor: {
+      default: "var(--hraness-material-warm-plane, transparent)",
+      [itemFocusedOrHovered]: accent,
+      [forcedColors]: "Highlight",
+    },
+    color: {
+      default: popoverForeground,
+      [itemFocusedOrHovered]: accentForeground,
+      [forcedColors]: "HighlightText",
+    },
+    fontWeight: "var(--font-weight-medium, 550)",
+  },
+  menu: {
+    display: "grid",
+    "max-block-size": "min(24rem, 70vh)",
+    outlineStyle: "none",
+    overflow: "auto",
+    paddingBlock: "0.25rem",
+    paddingInline: "0.25rem",
+  },
+  menuRoot: {
+    // Lantern tokens exist only inside a data-hraness-material="lantern"
+    // island, so each chain falls through to the palette outside one.
+    "--hraness-appearance-accent": lanternAccent,
+    "--hraness-appearance-accent-foreground": lanternAccentForeground,
+    "--hraness-appearance-control-background":
+      "var(--hraness-material-plane, var(--ui-background, Canvas))",
+    "--hraness-appearance-control-border":
+      "var(--hraness-material-seam, var(--ui-input, GrayText))",
+    "--hraness-appearance-control-foreground":
+      "var(--hraness-material-ink, var(--ui-foreground, CanvasText))",
+    "--hraness-appearance-focus":
+      "var(--hraness-material-focus, var(--ui-ring, Highlight))",
+    "--hraness-appearance-popover-background": lanternPopoverBackground,
+    "--hraness-appearance-popover-foreground": lanternPopoverForeground,
+    color: "var(--hraness-appearance-control-foreground)",
+    position: "relative",
+  },
+  notReady: {
+    opacity: 0.64,
+  },
+  popover: {
+    borderImageSource: "none",
+    borderImageSlice: "100%",
+    borderImageWidth: "1",
+    borderImageOutset: "0",
+    borderImageRepeat: "stretch",
+    backgroundAttachment: "scroll",
+    backgroundClip: "border-box",
+    backgroundImage: "none",
+    backgroundOrigin: "padding-box",
+    backgroundPosition: "0% 0%",
+    backgroundRepeat: "repeat",
+    backgroundSize: "auto auto",
+    backgroundColor:
+      `var(--hraness-appearance-popover-background, ${lanternPopoverBackground})`,
+    borderColor: {
+      default: controlBorder,
+      [forcedColors]: "CanvasText",
+    },
+    borderRadius: "var(--radius-lg, 0.75rem)",
+    borderStyle: "solid",
+    borderWidth: 1,
+    boxShadow: {
+      default:
+        "var(--hraness-material-lift, var(--elevation-overlay, 0 18px 48px -18px rgb(0 0 0 / 32%)))",
+      [forcedColors]: "none",
+    },
+    color: popoverForeground,
+    display: {
+      default: null,
+      [hidden]: "none",
+    },
+    forcedColorAdjust: {
+      default: null,
+      [forcedColors]: "auto",
+    },
+    "max-inline-size": "calc(100vw - 2rem)",
+    outlineStyle: "none",
+    overflow: "hidden",
+    "inline-size": "min(12rem, calc(100vw - 2rem))",
+    "z-index": "var(--z-tooltip, 3000)",
+  },
+  root: {
+    display: "inline-flex",
+    "min-inline-size": 0,
+  },
+  trigger: {
+    borderImageSource: "none",
+    borderImageSlice: "100%",
+    borderImageWidth: "1",
+    borderImageOutset: "0",
+    borderImageRepeat: "stretch",
+    backgroundAttachment: { default: "scroll", [hovered]: "scroll" },
+    backgroundClip: { default: "border-box", [hovered]: "border-box" },
+    backgroundImage: { default: "none", [hovered]: "none" },
+    backgroundOrigin: { default: "padding-box", [hovered]: "padding-box" },
+    backgroundPosition: { default: "0% 0%", [hovered]: "0% 0%" },
+    backgroundRepeat: { default: "repeat", [hovered]: "repeat" },
+    backgroundSize: { default: "auto auto", [hovered]: "auto auto" },
+    backgroundColor: {
+      default:
+        "var(--hraness-appearance-control-background, var(--hraness-material-plane, var(--ui-background, Canvas)))",
+      [hovered]: accent,
+    },
+    borderColor: {
+      default: controlBorder,
+      [forcedColors]: "CanvasText",
+    },
+    borderRadius: "var(--radius-md, 0.5rem)",
+    borderStyle: "solid",
+    borderWidth: 1,
+    // Lantern raises the trigger at rest and sets it into the plane while
+    // pressed. Both tokens are undefined outside Lantern and none in forced
+    // colors, so other palettes keep a flat trigger.
+    boxShadow: {
+      default: "var(--hraness-material-raised, none)",
+      [focusVisible]:
+        "0 0 0 4px color-mix(in srgb, var(--hraness-appearance-focus, var(--hraness-material-focus, var(--ui-ring, Highlight))) 24%, transparent)",
+      [pressed]: "var(--hraness-material-inset, none)",
+      [forcedColors]: "none",
+    },
+    color: {
+      default:
+        "var(--hraness-appearance-control-foreground, var(--hraness-material-ink, var(--ui-foreground, CanvasText)))",
+      [hovered]: accentForeground,
+    },
+    cursor: {
+      default: "pointer",
+      [disabled]: "not-allowed",
+    },
+    display: "inline-grid",
+    fontFamily: "inherit",
+    fontFeatureSettings: "inherit",
+    fontKerning: "inherit",
+    fontLanguageOverride: "inherit",
+    fontOpticalSizing: "inherit",
+    fontSizeAdjust: "inherit",
+    fontVariationSettings: "inherit",
+    fontSize: "inherit",
+    fontStretch: "inherit",
+    fontStyle: "inherit",
+    fontVariant: "inherit",
+    fontWeight: "inherit",
+    forcedColorAdjust: {
+      default: null,
+      [forcedColors]: "auto",
+    },
+    "inline-size": {
+      default: "2rem",
+      [coarsePointer]: "3rem",
+    },
+    lineHeight: "inherit",
+    "min-block-size": {
+      default: "2rem",
+      [coarsePointer]: "3rem",
+    },
+    "min-inline-size": {
+      default: "2rem",
+      [coarsePointer]: "3rem",
+    },
+    opacity: {
+      default: null,
+      [disabled]: 0.5,
+    },
+    outlineColor: {
+      default: null,
+      [focusVisible]:
+        "var(--hraness-appearance-focus, var(--hraness-material-focus, var(--ui-ring, Highlight)))",
+      [forcedColors]: "Highlight",
+    },
+    outlineOffset: {
+      default: null,
+      [focusVisible]: 2,
+    },
+    outlineStyle: {
+      default: "none",
+      [focusVisible]: "solid",
+    },
+    outlineWidth: {
+      default: null,
+      [focusVisible]: 2,
+    },
+    paddingBlock: 0,
+    paddingInline: 0,
+    placeItems: "center",
+    touchAction: "manipulation",
+    transform: {
+      default: null,
+      [pressed]: "translateY(1px)",
+    },
+    transitionDelay: "0s, 0s, 0s, 0s, 0s",
+    transitionDuration: {
+      default: "120ms, 120ms, 120ms, 120ms, 120ms",
+      [reducedMotion]: "0.01ms",
+    },
+    transitionProperty:
+      "background-color, border-color, box-shadow, color, transform",
+    transitionTimingFunction:
+      "cubic-bezier(0.2, 0, 0, 1), cubic-bezier(0.2, 0, 0, 1), cubic-bezier(0.2, 0, 0, 1), cubic-bezier(0.2, 0, 0, 1), cubic-bezier(0.2, 0, 0, 1)",
+  },
+});