@askrjs/themes 0.0.1

package/src/components/spacer/spacer.tsx

@@ -0,0 +1,58 @@
+import { Slot } from "@askrjs/askr/foundations";
+import { mergeProps } from "../_internal/merge-props";
+import { isCssLength, mergeLayoutStyles } from "../_internal/layout";
+import { isJsxElement, toChildArray } from "../_internal/jsx";
+import type { SpacerAsChildProps, SpacerNativeProps } from "./spacer.types";
+
+export function Spacer(props: SpacerNativeProps): JSX.Element;
+export function Spacer(props: SpacerAsChildProps): JSX.Element;
+export function Spacer(props: SpacerNativeProps | SpacerAsChildProps) {
+  const { asChild, children, grow, shrink, basis, axis, ref, style: userStyle, ...rest } = props;
+
+  const layoutStyle: Record<string, string | number> = {};
+
+  if (axis === "inline") {
+    if (shrink !== undefined && shrink !== 0) {
+      layoutStyle.flexShrink = shrink;
+    }
+    if (isCssLength(basis)) layoutStyle.width = basis!;
+  } else if (axis === "block") {
+    if (shrink !== undefined && shrink !== 0) {
+      layoutStyle.flexShrink = shrink;
+    }
+    if (isCssLength(basis)) layoutStyle.height = basis!;
+  } else {
+    if (grow !== undefined && grow !== 1) {
+      layoutStyle.flexGrow = grow;
+    }
+    if (shrink !== undefined && shrink !== 1) {
+      layoutStyle.flexShrink = shrink;
+    }
+    if (isCssLength(basis)) {
+      layoutStyle.flexBasis = basis!;
+    }
+  }
+
+  const finalProps = mergeProps(rest, {
+    ref,
+    "data-slot": "spacer",
+    "data-axis": axis,
+    style: mergeLayoutStyles(layoutStyle, userStyle),
+  });
+  const keyedChildren = toChildArray(children).map((child, index) => {
+    if (!isJsxElement(child) || child.key != null) {
+      return child;
+    }
+
+    return {
+      ...child,
+      key: `spacer-${index}`,
+    };
+  });
+
+  if (asChild) {
+    return <Slot asChild {...finalProps} children={children} />;
+  }
+
+  return <div {...finalProps}>{keyedChildren}</div>;
+}

package/src/components/spacer/spacer.types.ts

@@ -0,0 +1,30 @@
+import type { JSXElement, Ref } from "@askrjs/askr/foundations";
+
+export type SpacerAxis = "inline" | "block";
+
+export type SpacerOwnProps = {
+  /** flex-grow factor (default 1 when no axis is set). */
+  grow?: number;
+  /** flex-shrink factor (default 1 when no axis is set, 0 when axis is set). */
+  shrink?: number;
+  /** CSS flex-basis / width (axis=inline) / height (axis=block) value. Applied as inline style only when it is a real CSS length. */
+  basis?: string;
+  /** When set, renders a fixed space along the given axis instead of a flex-grow spacer. */
+  axis?: SpacerAxis;
+  children?: unknown;
+};
+
+export type SpacerNativeProps = Omit<JSX.IntrinsicElements["div"], "children" | "ref"> &
+  SpacerOwnProps & {
+    asChild?: false;
+    ref?: Ref<HTMLDivElement>;
+  };
+
+export type SpacerAsChildProps = SpacerOwnProps & {
+  asChild: true;
+  children: JSXElement;
+  ref?: Ref<unknown>;
+  style?: JSX.IntrinsicElements["div"]["style"];
+};
+
+export type SpacerProps = SpacerNativeProps | SpacerAsChildProps;

package/src/components/spinner/index.ts

@@ -0,0 +1,2 @@
+export { Spinner } from "./spinner";
+export type { SpinnerOwnProps, SpinnerProps } from "./spinner.types";

package/src/components/spinner/spinner.tsx

@@ -0,0 +1,21 @@
+import { ProgressCircle } from "@askrjs/ui";
+import type { SpinnerProps } from "./spinner.types";
+
+export function Spinner(props: SpinnerProps): JSX.Element {
+  const {
+    label,
+    "aria-label": ariaLabel,
+    ...rest
+  } = props as SpinnerProps & {
+    "aria-label"?: string;
+  };
+
+  return (
+    <ProgressCircle
+      {...rest}
+      aria-label={ariaLabel ?? label ?? "Loading"}
+      value={null}
+      getValueLabel={() => label ?? "Loading"}
+    />
+  );
+}

package/src/components/spinner/spinner.types.ts

@@ -0,0 +1,7 @@
+import type { ProgressCircleProps } from "@askrjs/ui";
+
+export type SpinnerOwnProps = Omit<ProgressCircleProps, "value" | "getValueLabel"> & {
+  label?: string;
+};
+
+export type SpinnerProps = SpinnerOwnProps;

package/src/components/stack/index.ts

@@ -0,0 +1,3 @@
+export { Stack } from "./stack";
+export { STACK_A11Y_CONTRACT, type StackA11yContract } from "./stack.a11y";
+export type { StackProps, StackOwnProps, StackDivProps, StackAsChildProps } from "./stack.types";

package/src/components/stack/stack.a11y.ts

@@ -0,0 +1,15 @@
+export const STACK_A11Y_CONTRACT = {
+  DATA_ATTRIBUTES: {
+    slot: "data-slot" as const,
+    layout: "data-ak-layout" as const,
+    gap: "data-gap" as const,
+    align: "data-align" as const,
+    justify: "data-justify" as const,
+    wrap: "data-wrap" as const,
+  },
+  SLOT_VALUES: {
+    root: "stack" as const,
+  },
+} as const;
+
+export type StackA11yContract = typeof STACK_A11Y_CONTRACT;

package/src/components/stack/stack.tsx

@@ -0,0 +1,13 @@
+import { Flex } from "../flex";
+import type { StackAsChildProps, StackDivProps } from "./stack.types";
+
+export function Stack(props: StackDivProps): JSX.Element;
+export function Stack(props: StackAsChildProps): JSX.Element;
+export function Stack(props: StackDivProps | StackAsChildProps) {
+  const { children, ...rest } = props;
+  return (
+    <Flex {...(rest as Record<string, unknown>)} data-slot="stack" direction="column">
+      {children}
+    </Flex>
+  );
+}

package/src/components/stack/stack.types.ts

@@ -0,0 +1,21 @@
+import type { JSXElement, Ref } from "@askrjs/askr/foundations";
+import type { FlexOwnProps } from "../flex/flex.types";
+
+export type StackOwnProps = Omit<FlexOwnProps, "direction" | "as"> & {
+  children?: unknown;
+};
+
+export type StackDivProps = Omit<JSX.IntrinsicElements["div"], "children" | "ref"> &
+  StackOwnProps & {
+    asChild?: false;
+    ref?: Ref<HTMLDivElement>;
+  };
+
+export type StackAsChildProps = StackOwnProps & {
+  asChild: true;
+  children: JSXElement;
+  ref?: Ref<unknown>;
+  style?: JSX.IntrinsicElements["div"]["style"];
+};
+
+export type StackProps = StackDivProps | StackAsChildProps;

package/src/components/theme/index.ts

@@ -0,0 +1,10 @@
+export { DEFAULT_THEME_OPTIONS, ThemePicker, ThemeProvider, ThemeToggle, useTheme } from "./theme";
+export type {
+  ThemeContextValue,
+  ThemeName,
+  ThemeOption,
+  ThemePickerProps,
+  ThemeProviderProps,
+  ThemeToggleProps,
+  ThemeToggleRenderContext,
+} from "./theme";

package/src/components/theme/theme.tsx

@@ -0,0 +1,260 @@
+import { defineContext, readContext, state } from "@askrjs/askr";
+import { resource } from "@askrjs/askr/resources";
+import { Button } from "@askrjs/ui";
+import type { ButtonNativeProps, PressEvent } from "@askrjs/ui";
+
+export type ThemeName = "light" | "dark" | "system" | (string & {});
+
+export type ThemeOption = {
+  value: ThemeName;
+  label: string;
+};
+
+export type ThemeContextValue = {
+  theme: () => ThemeName;
+  setTheme: (theme: ThemeName) => void;
+  themes: readonly ThemeOption[];
+  storageKey: string;
+};
+
+export type ThemeProviderProps = {
+  children?: unknown;
+  defaultTheme?: ThemeName;
+  themes?: readonly ThemeOption[];
+  storageKey?: string;
+};
+
+export type ThemePickerProps = Omit<
+  JSX.IntrinsicElements["select"],
+  "children" | "value" | "defaultValue" | "onChange"
+> & {
+  themes?: readonly ThemeOption[];
+  label?: string;
+};
+
+export type ThemeToggleRenderContext = {
+  theme: ThemeName;
+  nextTheme: ThemeName;
+};
+
+export type ThemeToggleProps = Omit<ButtonNativeProps, "children" | "onPress"> & {
+  children?: unknown | ((context: ThemeToggleRenderContext) => unknown);
+  lightIcon?: unknown;
+  darkIcon?: unknown;
+  systemIcon?: unknown;
+  toggleThemes?: readonly ThemeName[];
+  onPress?: (event: PressEvent) => void;
+};
+
+export const DEFAULT_THEME_OPTIONS: readonly ThemeOption[] = [
+  { value: "system", label: "System" },
+  { value: "light", label: "Light" },
+  { value: "dark", label: "Dark" },
+];
+
+const DEFAULT_STORAGE_KEY = "askr-theme";
+
+const ThemeContext = defineContext<ThemeContextValue>({
+  theme: () => "system",
+  setTheme: () => undefined,
+  themes: DEFAULT_THEME_OPTIONS,
+  storageKey: DEFAULT_STORAGE_KEY,
+});
+
+export function useTheme(): ThemeContextValue {
+  return readContext(ThemeContext);
+}
+
+export function ThemeProvider(props: ThemeProviderProps): JSX.Element {
+  const {
+    children,
+    defaultTheme = "system",
+    themes = DEFAULT_THEME_OPTIONS,
+    storageKey = DEFAULT_STORAGE_KEY,
+  } = props;
+
+  const themeState = state<ThemeName>(readStoredTheme(storageKey) ?? defaultTheme);
+
+  const setTheme = (nextTheme: ThemeName) => {
+    themeState.set(nextTheme);
+    writeStoredTheme(storageKey, nextTheme);
+    syncThemeRoot(nextTheme);
+  };
+
+  const value: ThemeContextValue = {
+    theme: themeState,
+    setTheme,
+    themes,
+    storageKey,
+  };
+
+  const currentTheme = themeState();
+
+  return (
+    <ThemeContext.Scope value={value}>
+      <ThemeRootSync theme={currentTheme} />
+      <div data-slot="theme-provider">{children}</div>
+    </ThemeContext.Scope>
+  );
+}
+
+function ThemeRootSync(props: { theme: ThemeName }): JSX.Element | null {
+  const { theme } = props;
+
+  resource(
+    ({ signal }: { signal: AbortSignal }) => {
+      if (typeof window === "undefined") {
+        syncThemeRoot(theme);
+        return null;
+      }
+
+      const timeoutId = window.setTimeout(() => {
+        if (!signal.aborted) {
+          syncThemeRoot(theme);
+        }
+      }, 0);
+
+      signal.addEventListener(
+        "abort",
+        () => {
+          window.clearTimeout(timeoutId);
+        },
+        { once: true },
+      );
+
+      return null;
+    },
+    [theme],
+  );
+
+  return null;
+}
+
+export function ThemePicker(props: ThemePickerProps): JSX.Element {
+  const theme = useTheme();
+  const { themes = theme.themes, label = "Theme", ...rest } = props;
+
+  return (
+    <select
+      {...rest}
+      aria-label={rest["aria-label"] ?? label}
+      data-slot="theme-picker"
+      value={theme.theme()}
+      onChange={(event: Event) => {
+        const target = event.currentTarget as HTMLSelectElement;
+        theme.setTheme(target.value as ThemeName);
+      }}
+    >
+      {themes.map((option) => (
+        <option key={option.value} value={option.value}>
+          {option.label}
+        </option>
+      ))}
+    </select>
+  );
+}
+
+export function ThemeToggle(props: ThemeToggleProps): JSX.Element {
+  const theme = useTheme();
+  const {
+    children,
+    lightIcon,
+    darkIcon,
+    systemIcon,
+    toggleThemes = ["light", "dark"],
+    onPress,
+    ...rest
+  } = props;
+
+  const currentTheme = theme.theme();
+  const nextTheme = getNextTheme(currentTheme, toggleThemes);
+  const renderContext = { theme: currentTheme, nextTheme };
+  const ariaLabel = (rest as Record<string, unknown>)["aria-label"];
+  const themedIcon = resolveThemeToggleIcon(currentTheme, nextTheme, {
+    lightIcon,
+    darkIcon,
+    systemIcon,
+  });
+  const content =
+    typeof children === "function" ? children(renderContext) : (children ?? themedIcon);
+
+  return (
+    <Button
+      {...(rest as ButtonNativeProps)}
+      aria-label={typeof ariaLabel === "string" ? ariaLabel : `Switch to ${nextTheme} theme`}
+      data-theme-control="toggle"
+      data-theme-choice={currentTheme}
+      data-next-theme={nextTheme}
+      onPress={(event) => {
+        onPress?.(event);
+        if (!event.defaultPrevented) theme.setTheme(nextTheme);
+      }}
+    >
+      {content}
+    </Button>
+  );
+}
+
+function getNextTheme(currentTheme: ThemeName, themes: readonly ThemeName[]): ThemeName {
+  if (themes.length === 0) return currentTheme;
+  const index = themes.indexOf(currentTheme);
+  return themes[index >= 0 && index < themes.length - 1 ? index + 1 : 0]!;
+}
+
+function getThemeIcon(
+  theme: ThemeName,
+  icons: Pick<ThemeToggleProps, "lightIcon" | "darkIcon" | "systemIcon">,
+): unknown {
+  if (theme === "light") return icons.lightIcon;
+  if (theme === "dark") return icons.darkIcon;
+  if (theme === "system") return icons.systemIcon;
+  return undefined;
+}
+
+export function resolveThemeToggleIcon(
+  theme: ThemeName,
+  nextTheme: ThemeName,
+  icons: Pick<ThemeToggleProps, "lightIcon" | "darkIcon" | "systemIcon">,
+): unknown {
+  return getThemeIcon(theme, icons) ?? getThemeIcon(nextTheme, icons);
+}
+
+function syncThemeRoot(themeChoice: ThemeName | null | undefined): void {
+  if (typeof document === "undefined") {
+    return;
+  }
+
+  const html = document.documentElement;
+
+  if (themeChoice == null) {
+    html.removeAttribute("data-theme");
+    html.removeAttribute("data-theme-choice");
+    return;
+  }
+
+  html.setAttribute("data-theme-choice", themeChoice);
+
+  if (themeChoice === "system") {
+    html.removeAttribute("data-theme");
+  } else {
+    html.setAttribute("data-theme", themeChoice);
+  }
+}
+
+function readStoredTheme(storageKey: string): ThemeName | undefined {
+  if (typeof window === "undefined") return undefined;
+  try {
+    return (window.localStorage.getItem(storageKey) as ThemeName | null) ?? undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+function writeStoredTheme(storageKey: string, theme: ThemeName): void {
+  if (typeof window === "undefined") return;
+  try {
+    window.localStorage.setItem(storageKey, theme);
+  } catch {
+    // Storage can be unavailable in private or locked-down browser contexts.
+  }
+}

package/src/components/topbar-layout/index.ts

@@ -0,0 +1,3 @@
+export { TopbarLayout } from "./topbar-layout";
+export { TOPBAR_LAYOUT_A11Y_CONTRACT, type TopbarLayoutA11yContract } from "./topbar-layout.a11y";
+export type { TopbarLayoutProps } from "./topbar-layout.types";

package/src/components/topbar-layout/topbar-layout.a11y.ts

@@ -0,0 +1,14 @@
+export const TOPBAR_LAYOUT_A11Y_CONTRACT = {
+  DATA_ATTRIBUTES: {
+    slot: "data-slot" as const,
+    topbarHeight: "data-topbar-height" as const,
+    gap: "data-gap" as const,
+  },
+  SLOT_VALUES: {
+    root: "topbar-layout" as const,
+    navbar: "navbar" as const,
+    main: "main" as const,
+  },
+} as const;
+
+export type TopbarLayoutA11yContract = typeof TOPBAR_LAYOUT_A11Y_CONTRACT;

package/src/components/topbar-layout/topbar-layout.tsx

@@ -0,0 +1,39 @@
+import { isCssLength, mergeLayoutStyles, serializeValueIf } from "../_internal/layout";
+import type { TopbarLayoutProps } from "./topbar-layout.types";
+
+function isThemeGapToken(value: unknown): value is string {
+  return typeof value === "string" && ["sm", "md", "lg", "xl"].includes(value.trim());
+}
+
+export function TopbarLayout(props: TopbarLayoutProps): JSX.Element {
+  const { topbar, children, topbarHeight, gap, ref, style: userStyle, ...rest } = props;
+
+  const wrapperStyle: Record<string, string | number> = {};
+  if (isCssLength(gap)) wrapperStyle.gap = gap!;
+
+  const navbarStyle: Record<string, string | number> = {};
+  if (isCssLength(topbarHeight)) navbarStyle.height = topbarHeight!;
+
+  return (
+    <div
+      {...rest}
+      ref={ref}
+      data-slot="topbar-layout"
+      data-gap={serializeValueIf(gap, isThemeGapToken)}
+      style={mergeLayoutStyles(wrapperStyle, userStyle)}
+    >
+      {[
+        <header
+          key="topbar-layout-navbar"
+          data-slot="navbar"
+          style={mergeLayoutStyles(navbarStyle, undefined)}
+        >
+          {topbar}
+        </header>,
+        <main key="topbar-layout-main" data-slot="main">
+          {children}
+        </main>,
+      ]}
+    </div>
+  );
+}

package/src/components/topbar-layout/topbar-layout.types.ts

@@ -0,0 +1,13 @@
+import type { Ref } from "@askrjs/askr/foundations";
+
+export type TopbarLayoutProps = Omit<JSX.IntrinsicElements["div"], "children" | "ref"> & {
+  /** Content rendered into the topbar/navbar slot (header). */
+  topbar?: unknown;
+  /** Content rendered into the main slot. */
+  children?: unknown;
+  /** CSS height for the topbar. Applied as inline style only when it is a real CSS length. */
+  topbarHeight?: string;
+  /** CSS gap between topbar and main. Applied as inline style only when it is a real CSS length. */
+  gap?: string;
+  ref?: Ref<HTMLDivElement>;
+};

package/src/css.d.ts

@@ -0,0 +1 @@
+declare module "*.css";

package/src/index.css

@@ -0,0 +1 @@
+@import "./themes/default/index.css";

package/src/jsx.d.ts

@@ -0,0 +1,23 @@
+import type { JSXElement } from "@askrjs/askr/foundations";
+
+declare global {
+  namespace JSX {
+    interface Element extends JSXElement {
+      readonly __askrThemesJsxElementBrand?: never;
+    }
+
+    interface IntrinsicElements {
+      [elem: string]: Record<string, unknown>;
+    }
+
+    interface ElementAttributesProperty {
+      props: Record<string, unknown>;
+    }
+
+    interface ElementChildrenAttribute {
+      children: unknown;
+    }
+  }
+}
+
+export {};

package/src/themes/default/index.css

@@ -0,0 +1,48 @@
+@import "./tokens.css";
+@import "./styles/base/typography.css";
+@import "./styles/base/icon.css";
+@import "./styles/base/utilities.css";
+@import "./styles/layout/layout.css";
+@import "./styles/layout/responsive-layout.css";
+@import "./styles/layout/patterns.css";
+@import "./styles/layout/aspect-ratio.css";
+@import "./styles/shell/theme.css";
+@import "./styles/shell/header.css";
+@import "./styles/shell/navbar.css";
+@import "./styles/actions/button.css";
+@import "./styles/actions/toggle.css";
+@import "./styles/actions/toggle-group.css";
+@import "./styles/forms/input.css";
+@import "./styles/forms/textarea.css";
+@import "./styles/forms/form.css";
+@import "./styles/forms/checkbox.css";
+@import "./styles/forms/switch.css";
+@import "./styles/forms/radio-group.css";
+@import "./styles/forms/select.css";
+@import "./styles/forms/slider.css";
+@import "./styles/forms/label.css";
+@import "./styles/display/card.css";
+@import "./styles/display/progress.css";
+@import "./styles/display/progress-circle.css";
+@import "./styles/display/badge.css";
+@import "./styles/display/skeleton.css";
+@import "./styles/display/avatar.css";
+@import "./styles/display/separator.css";
+@import "./styles/display/table.css";
+@import "./styles/display/scroll-area.css";
+@import "./styles/display/spinner.css";
+@import "./styles/display/coverage.css";
+@import "./styles/navigation/breadcrumb.css";
+@import "./styles/navigation/tabs.css";
+@import "./styles/navigation/menu.css";
+@import "./styles/navigation/menubar.css";
+@import "./styles/navigation/navigation-menu.css";
+@import "./styles/disclosure/accordion.css";
+@import "./styles/disclosure/collapsible.css";
+@import "./styles/overlays/alert-dialog.css";
+@import "./styles/overlays/dropdown-menu.css";
+@import "./styles/overlays/toast.css";
+@import "./styles/overlays/dialog.css";
+@import "./styles/overlays/popover.css";
+@import "./styles/overlays/hover-card.css";
+@import "./styles/overlays/tooltip.css";