@misoto22/kioku-ui 0.0.0

package/src/styles/reset.css

@@ -0,0 +1,35 @@
+*,
+*::before,
+*::after {
+  box-sizing: border-box;
+}
+
+html {
+  -webkit-text-size-adjust: 100%;
+  text-size-adjust: 100%;
+}
+
+body {
+  min-height: 100%;
+  margin: 0;
+  font-family: inherit;
+}
+
+button,
+input,
+select,
+textarea {
+  color: inherit;
+  font: inherit;
+}
+
+@media (prefers-reduced-motion: reduce) {
+  *,
+  *::before,
+  *::after {
+    scroll-behavior: auto !important;
+    animation-duration: 0.01ms !important;
+    animation-iteration-count: 1 !important;
+    transition-duration: 0.01ms !important;
+  }
+}

package/src/theme/Theme.doc.ts

@@ -0,0 +1,38 @@
+import type {ComponentDoc} from '../docs/types.js';
+
+export const themeProviderDoc = {
+  name: 'ThemeProvider',
+  description:
+    'Applies one validated theme definition and exposes theme selection to descendants.',
+  props: [
+    {
+      name: 'children',
+      description: 'Supplies the themed application subtree.',
+      required: true,
+    },
+    {
+      name: 'defaultDensity',
+      description:
+        'Selects the initial spatial scale when persistence has no value.',
+    },
+    {
+      name: 'defaultThemeId',
+      description: 'Selects the initial theme when persistence has no value.',
+      required: true,
+    },
+    {
+      name: 'persistence',
+      description:
+        'Reads and writes the selected theme through a host adapter.',
+    },
+    {
+      name: 'themes',
+      description: 'Supplies the complete set of valid theme definitions.',
+      required: true,
+    },
+  ],
+  inheritedProps: ['No inherited DOM attributes'],
+  example:
+    '<ThemeProvider defaultThemeId={hostDefaultThemeId} themes={hostThemes}>...</ThemeProvider>',
+  storyId: 'core-theme-provider--default',
+} satisfies ComponentDoc;

package/src/theme/Theme.tsx

@@ -0,0 +1,195 @@
+import * as stylex from '@stylexjs/stylex';
+import {
+  createContext,
+  useCallback,
+  useContext,
+  useMemo,
+  useState,
+  type CSSProperties,
+  type ReactNode,
+} from 'react';
+
+import {
+  tokenCustomProperties,
+  tokenNames,
+  validateThemeDefinition,
+  type ThemeDefinition,
+} from '../tokens/contracts.js';
+import {semanticTokens} from '../authoring.stylex.js';
+
+/*
+ * Grain. Paper is never flat, and a flat fill is the strongest tell that a
+ * surface was generated rather than made. Drawn with feTurbulence, so nothing
+ * is fetched and nothing is stored, and masked rather than blended so the
+ * speckle takes the theme's own ink instead of a grey wash. A theme that wants
+ * none makes the colour transparent and pays nothing else.
+ *
+ * It sits above the content, where a printed texture sits. The stacking step
+ * is 1 rather than a nine-thousand, so a host's own layers still out-rank it.
+ */
+const grainMask =
+  "url(\"data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' width='140' height='140'%3E%3Cfilter id='n'%3E%3CfeTurbulence type='fractalNoise' baseFrequency='0.82' numOctaves='4' stitchTiles='stitch'/%3E%3C/filter%3E%3Crect width='140' height='140' filter='url(%23n)'/%3E%3C/svg%3E\")";
+
+const styles = stylex.create({
+  root: {
+    // Inherited, so the theme root sets it once for the tree beneath it. A
+    // Japanese face wants proportional spacing that a Latin one does not, and
+    // which it is belongs to the theme rather than to any component.
+    fontFeatureSettings: semanticTokens.fontFeatureSettings,
+    position: 'relative',
+    '::after': {
+      backgroundColor: semanticTokens.textureGrain,
+      content: '',
+      inset: 0,
+      maskImage: grainMask,
+      pointerEvents: 'none',
+      position: 'absolute',
+      zIndex: 1,
+    },
+  },
+});
+
+interface CompiledStyleXVarGroup {
+  readonly __varGroupHash__: string;
+}
+
+// StyleX emits semantic-token bridge variables for this generated scope. The
+// host theme values live on ThemeProvider, so the scope must live there too.
+const semanticTokenScopeClass = (
+  semanticTokens as unknown as CompiledStyleXVarGroup
+).__varGroupHash__;
+
+export type Density = 'compact' | 'standard';
+
+const densities: readonly Density[] = ['compact', 'standard'];
+
+// A theme pack fulfills the token contract twice, once per density. Density is
+// therefore a root attribute rather than a token value: the pack's CSS decides
+// what each step measures, and the library only says which one is selected.
+export interface ThemePersistence {
+  read(): string | undefined;
+  write(themeId: string): void;
+  readDensity?(): string | undefined;
+  writeDensity?(density: Density): void;
+}
+
+export interface ThemeProviderProps {
+  readonly children: ReactNode;
+  readonly defaultDensity?: Density;
+  readonly defaultThemeId: string;
+  readonly persistence?: ThemePersistence;
+  readonly themes: readonly ThemeDefinition[];
+}
+
+export interface ThemeContextValue {
+  readonly density: Density;
+  readonly setDensity: (density: Density) => void;
+  readonly setThemeId: (themeId: string) => void;
+  readonly theme: ThemeDefinition;
+}
+
+const ThemeContext = createContext<ThemeContextValue | undefined>(undefined);
+
+function validateThemes(themes: readonly ThemeDefinition[]) {
+  const themeIds = new Set<string>();
+
+  for (const theme of themes) {
+    if (themeIds.has(theme.id)) {
+      throw new Error(`Duplicate theme ID: ${theme.id}`);
+    }
+    themeIds.add(theme.id);
+
+    const missingTokens = validateThemeDefinition(theme);
+    if (missingTokens.length > 0) {
+      throw new Error(
+        `Theme "${theme.id}" is missing token roles: ${missingTokens.join(', ')}`,
+      );
+    }
+  }
+}
+
+function requiredDensity(density: string | undefined, fallback: Density) {
+  return densities.includes(density as Density)
+    ? (density as Density)
+    : fallback;
+}
+
+function requiredTheme(themes: readonly ThemeDefinition[], themeId: string) {
+  const theme = themes.find(({id}) => id === themeId);
+  if (!theme) {
+    throw new Error(`Unknown theme ID: ${themeId}`);
+  }
+  return theme;
+}
+
+function themeStyle(theme: ThemeDefinition): CSSProperties {
+  return Object.fromEntries(
+    tokenNames.map((tokenName) => [
+      tokenCustomProperties[tokenName],
+      theme.tokens[tokenName],
+    ]),
+  ) as CSSProperties;
+}
+
+export function ThemeProvider({
+  children,
+  defaultDensity = 'compact',
+  defaultThemeId,
+  persistence,
+  themes,
+}: ThemeProviderProps) {
+  validateThemes(themes);
+
+  const [themeId, setCurrentThemeId] = useState(
+    () => persistence?.read() ?? defaultThemeId,
+  );
+  const theme = requiredTheme(themes, themeId);
+  const setThemeId = useCallback(
+    (nextThemeId: string) => {
+      requiredTheme(themes, nextThemeId);
+      persistence?.write(nextThemeId);
+      setCurrentThemeId(nextThemeId);
+    },
+    [persistence, themes],
+  );
+  const [density, setCurrentDensity] = useState(() =>
+    requiredDensity(persistence?.readDensity?.(), defaultDensity),
+  );
+  const setDensity = useCallback(
+    (nextDensity: Density) => {
+      const resolved = requiredDensity(nextDensity, defaultDensity);
+      persistence?.writeDensity?.(resolved);
+      setCurrentDensity(resolved);
+    },
+    [defaultDensity, persistence],
+  );
+  const value = useMemo(
+    () => ({density, setDensity, setThemeId, theme}),
+    [density, setDensity, setThemeId, theme],
+  );
+
+  const {className, style} = stylex.props(styles.root);
+
+  return (
+    <ThemeContext value={value}>
+      <div
+        className={[semanticTokenScopeClass, className]
+          .filter(Boolean)
+          .join(' ')}
+        data-density={density}
+        data-theme={theme.id}
+        style={{...style, ...themeStyle(theme)}}
+      >
+        {children}
+      </div>
+    </ThemeContext>
+  );
+}
+
+export function useTheme(): ThemeContextValue {
+  const theme = useContext(ThemeContext);
+  if (!theme) {
+    throw new Error('useTheme must be used within a ThemeProvider');
+  }
+  return theme;
+}

package/src/theme/index.ts

@@ -0,0 +1,9 @@
+export {
+  ThemeProvider,
+  useTheme,
+  type Density,
+  type ThemeContextValue,
+  type ThemePersistence,
+  type ThemeProviderProps,
+} from './Theme.js';
+export type {ThemeDefinition} from '../tokens/contracts.js';

package/src/tokens/contracts.ts

@@ -0,0 +1,210 @@
+type Roles<Group extends string, Role extends string> = Readonly<{
+  [Name in Role]: `${Group}.${Name}`;
+}>;
+
+type ColorRole =
+  | 'canvas'
+  | 'surface'
+  | 'surfaceRaised'
+  | 'surfaceMuted'
+  | 'text'
+  | 'textSecondary'
+  | 'textMuted'
+  | 'textOnAccent'
+  | 'accent'
+  | 'accentHover'
+  | 'accentActive'
+  | 'overlayHover'
+  | 'overlayActive'
+  | 'disabledSurface'
+  | 'disabledText'
+  | 'focus';
+type BorderRole =
+  'default' | 'strong' | 'interactive' | 'disabled' | 'width' | 'style';
+type StatusRole =
+  | 'infoSurface'
+  | 'infoText'
+  | 'successSurface'
+  | 'successText'
+  | 'warningSurface'
+  | 'warningText'
+  | 'dangerSurface'
+  | 'dangerText';
+type FocusRole = 'width' | 'offset';
+type TypographyRole =
+  | 'fontFamilyBody'
+  | 'fontFamilyHeading'
+  | 'fontFamilyDisplay'
+  | 'fontFamilyMono'
+  | 'fontFeatureSettings'
+  | 'fontSizeXs'
+  | 'fontSizeSm'
+  | 'fontSizeMd'
+  | 'fontSizeLg'
+  | 'fontSizeXl'
+  | 'fontSize2xl'
+  | 'fontWeightRegular'
+  | 'fontWeightMedium'
+  | 'fontWeightStrong'
+  | 'lineHeightBody'
+  | 'lineHeightHeading';
+type SpacingRole = 'xs' | 'sm' | 'md' | 'lg' | 'xl' | '2xl';
+type RadiusRole = 'inner' | 'element' | 'container' | 'page' | 'full';
+type SizeRole = 'controlSm' | 'controlMd' | 'controlLg' | 'hitTarget';
+type TextureRole = 'grain';
+type ElevationRole = 'low' | 'medium' | 'high';
+type MotionRole =
+  | 'durationFast'
+  | 'durationModerate'
+  | 'durationSlow'
+  | 'easingStandard'
+  | 'easingEmphasized';
+
+export interface TokenContract {
+  readonly color: Roles<'color', ColorRole>;
+  readonly border: Roles<'border', BorderRole>;
+  readonly status: Roles<'status', StatusRole>;
+  readonly focus: Roles<'focus', FocusRole>;
+  readonly typography: Roles<'typography', TypographyRole>;
+  readonly spacing: Roles<'spacing', SpacingRole>;
+  readonly radius: Roles<'radius', RadiusRole>;
+  readonly size: Roles<'size', SizeRole>;
+  readonly elevation: Roles<'elevation', ElevationRole>;
+  readonly texture: Roles<'texture', TextureRole>;
+  readonly motion: Roles<'motion', MotionRole>;
+}
+
+export const tokenContract = {
+  color: {
+    canvas: 'color.canvas',
+    surface: 'color.surface',
+    surfaceRaised: 'color.surfaceRaised',
+    surfaceMuted: 'color.surfaceMuted',
+    text: 'color.text',
+    textSecondary: 'color.textSecondary',
+    textMuted: 'color.textMuted',
+    textOnAccent: 'color.textOnAccent',
+    accent: 'color.accent',
+    accentHover: 'color.accentHover',
+    accentActive: 'color.accentActive',
+    overlayHover: 'color.overlayHover',
+    overlayActive: 'color.overlayActive',
+    disabledSurface: 'color.disabledSurface',
+    disabledText: 'color.disabledText',
+    focus: 'color.focus',
+  },
+  border: {
+    default: 'border.default',
+    strong: 'border.strong',
+    interactive: 'border.interactive',
+    disabled: 'border.disabled',
+    width: 'border.width',
+    style: 'border.style',
+  },
+  status: {
+    infoSurface: 'status.infoSurface',
+    infoText: 'status.infoText',
+    successSurface: 'status.successSurface',
+    successText: 'status.successText',
+    warningSurface: 'status.warningSurface',
+    warningText: 'status.warningText',
+    dangerSurface: 'status.dangerSurface',
+    dangerText: 'status.dangerText',
+  },
+  focus: {
+    width: 'focus.width',
+    offset: 'focus.offset',
+  },
+  typography: {
+    fontFamilyBody: 'typography.fontFamilyBody',
+    fontFamilyHeading: 'typography.fontFamilyHeading',
+    fontFamilyDisplay: 'typography.fontFamilyDisplay',
+    fontFamilyMono: 'typography.fontFamilyMono',
+    fontFeatureSettings: 'typography.fontFeatureSettings',
+    fontSizeXs: 'typography.fontSizeXs',
+    fontSizeSm: 'typography.fontSizeSm',
+    fontSizeMd: 'typography.fontSizeMd',
+    fontSizeLg: 'typography.fontSizeLg',
+    fontSizeXl: 'typography.fontSizeXl',
+    fontSize2xl: 'typography.fontSize2xl',
+    fontWeightRegular: 'typography.fontWeightRegular',
+    fontWeightMedium: 'typography.fontWeightMedium',
+    fontWeightStrong: 'typography.fontWeightStrong',
+    lineHeightBody: 'typography.lineHeightBody',
+    lineHeightHeading: 'typography.lineHeightHeading',
+  },
+  spacing: {
+    xs: 'spacing.xs',
+    sm: 'spacing.sm',
+    md: 'spacing.md',
+    lg: 'spacing.lg',
+    xl: 'spacing.xl',
+    '2xl': 'spacing.2xl',
+  },
+  radius: {
+    inner: 'radius.inner',
+    element: 'radius.element',
+    container: 'radius.container',
+    page: 'radius.page',
+    full: 'radius.full',
+  },
+  size: {
+    controlSm: 'size.controlSm',
+    controlMd: 'size.controlMd',
+    controlLg: 'size.controlLg',
+    hitTarget: 'size.hitTarget',
+  },
+  elevation: {
+    low: 'elevation.low',
+    medium: 'elevation.medium',
+    high: 'elevation.high',
+  },
+  texture: {
+    grain: 'texture.grain',
+  },
+  motion: {
+    durationFast: 'motion.durationFast',
+    durationModerate: 'motion.durationModerate',
+    durationSlow: 'motion.durationSlow',
+    easingStandard: 'motion.easingStandard',
+    easingEmphasized: 'motion.easingEmphasized',
+  },
+} as const satisfies TokenContract;
+
+type ContractGroup = (typeof tokenContract)[keyof typeof tokenContract];
+type Values<Value> = Value extends unknown ? Value[keyof Value] : never;
+
+export type TokenName = Values<ContractGroup>;
+
+export const tokenNames = Object.freeze(
+  Object.values(tokenContract).flatMap((group) => Object.values(group)),
+) as readonly TokenName[];
+
+export interface ThemeDefinition {
+  readonly id: string;
+  readonly label: string;
+  readonly tokens: Readonly<Record<TokenName, string>>;
+}
+
+export interface ThemeDefinitionCandidate {
+  readonly id: string;
+  readonly label?: string;
+  readonly tokens: Readonly<Partial<Record<TokenName, string>>>;
+}
+
+export function validateThemeDefinition(
+  theme: ThemeDefinitionCandidate,
+): TokenName[] {
+  return tokenNames.filter((name) => theme.tokens[name] === undefined);
+}
+
+export const tokenCustomProperties = Object.freeze(
+  Object.fromEntries(
+    tokenNames.map((name) => [
+      name,
+      `--kioku-ui-${name
+        .replaceAll('.', '-')
+        .replace(/[A-Z]/g, (character) => `-${character.toLowerCase()}`)}`,
+    ]),
+  ),
+) as Readonly<Record<TokenName, `--kioku-ui-${string}`>>;