@misoto22/kioku-ui 0.0.0 → 0.2.0

package/src/Icon/Icon.tsx

@@ -0,0 +1,83 @@
+import * as stylex from '@stylexjs/stylex';
+import type {SVGAttributes} from 'react';
+
+import {semanticTokens} from '../authoring.stylex.js';
+
+const styles = stylex.create({
+  base: {
+    display: 'inline-block',
+    fill: 'currentColor',
+    flexShrink: 0,
+    verticalAlign: 'middle',
+  },
+  sizeInherit: {height: '1em', width: '1em'},
+  sizeSm: {height: semanticTokens.fontSizeSm, width: semanticTokens.fontSizeSm},
+  sizeMd: {height: semanticTokens.fontSizeMd, width: semanticTokens.fontSizeMd},
+  sizeLg: {height: semanticTokens.fontSizeLg, width: semanticTokens.fontSizeLg},
+  tonePrimary: {color: semanticTokens.colorText},
+  toneSecondary: {color: semanticTokens.colorTextSecondary},
+  toneMuted: {color: semanticTokens.colorTextMuted},
+  toneAccent: {color: semanticTokens.colorAccent},
+});
+
+const sizes = {
+  inherit: styles.sizeInherit,
+  sm: styles.sizeSm,
+  md: styles.sizeMd,
+  lg: styles.sizeLg,
+} as const;
+
+const tones = {
+  primary: styles.tonePrimary,
+  secondary: styles.toneSecondary,
+  muted: styles.toneMuted,
+  accent: styles.toneAccent,
+} as const;
+
+/** Square sizes an icon can occupy, aligned to the typography scale. */
+export type IconSize = 'inherit' | 'sm' | 'md' | 'lg';
+
+/** Semantic colour roles an icon can adopt. */
+export type IconTone = 'inherit' | 'primary' | 'secondary' | 'muted' | 'accent';
+
+/** Props for the product-neutral SVG container. */
+export interface IconProps extends Omit<
+  SVGAttributes<SVGSVGElement>,
+  'aria-hidden' | 'aria-label' | 'className' | 'role'
+> {
+  readonly label?: string;
+  readonly size?: IconSize;
+  readonly tone?: IconTone;
+}
+
+/**
+ * Wraps caller-supplied SVG paths so the system owns sizing, colour, and
+ * accessible naming without shipping an icon set of its own.
+ */
+export function Icon({
+  children,
+  label,
+  size = 'inherit',
+  tone = 'inherit',
+  viewBox = '0 0 24 24',
+  ...props
+}: IconProps) {
+  const decorative = label === undefined;
+
+  return (
+    <svg
+      {...props}
+      aria-hidden={decorative ? 'true' : undefined}
+      aria-label={decorative ? undefined : label}
+      role={decorative ? undefined : 'img'}
+      {...stylex.props(
+        styles.base,
+        sizes[size],
+        tone !== 'inherit' && tones[tone],
+      )}
+      viewBox={viewBox}
+    >
+      {children}
+    </svg>
+  );
+}

package/src/Icon/index.ts

@@ -0,0 +1 @@
+export {Icon, type IconProps, type IconSize, type IconTone} from './Icon.js';

package/src/Indicator/Indicator.doc.ts

@@ -0,0 +1,21 @@
+import type {ComponentDoc} from '../docs/types.js';
+
+export const indicatorDoc = {
+  name: 'Indicator',
+  description: 'Attaches a count or dot to the control it wraps.',
+  props: [
+    {name: 'children', description: 'Supplies the control being marked.'},
+    {name: 'count', description: 'Shows a number; omit to show a plain dot.'},
+    {name: 'label', description: 'States what the indicator means.'},
+    {
+      name: 'max',
+      description: 'Caps the number before it reads as "max plus".',
+    },
+    {name: 'tone', description: 'Selects the semantic status colour.'},
+  ],
+  inheritedProps: [
+    'HTMLAttributes<HTMLSpanElement> except children and className',
+  ],
+  example: '<Indicator count={3} label="3 unread"><IconButton … /></Indicator>',
+  storyId: 'core-indicator--default',
+} satisfies ComponentDoc;

package/src/Indicator/Indicator.tsx

@@ -0,0 +1,99 @@
+import * as stylex from '@stylexjs/stylex';
+import type {HTMLAttributes, ReactNode} from 'react';
+
+import {semanticTokens} from '../authoring.stylex.js';
+import type {StatusTone} from '../Badge/index.js';
+
+const styles = stylex.create({
+  anchor: {display: 'inline-flex', position: 'relative'},
+  // The ring is painted in the surface behind the control, so the mark reads
+  // as sitting on top of it rather than fused to its edge.
+  badge: {
+    alignItems: 'center',
+    borderColor: semanticTokens.colorSurface,
+    borderRadius: semanticTokens.radiusFull,
+    borderStyle: semanticTokens.borderStyle,
+    borderWidth: semanticTokens.focusWidth,
+    display: 'inline-flex',
+    fontFamily: semanticTokens.fontFamilyMono,
+    fontSize: semanticTokens.fontSizeXs,
+    fontVariantNumeric: 'tabular-nums',
+    fontWeight: semanticTokens.fontWeightMedium,
+    insetBlockStart: 0,
+    insetInlineEnd: 0,
+    justifyContent: 'center',
+    letterSpacing: semanticTokens.letterSpacingMono,
+    lineHeight: 1,
+    minWidth: semanticTokens.spacingMd,
+    paddingInline: semanticTokens.spacingXs,
+    position: 'absolute',
+    transform: 'translate(35%, -35%)',
+  },
+  // The badge's ring is a gap cut in whatever sits beneath, and the dot wants
+  // it as much as the numeral does — so the dot grows to make room for it
+  // rather than dropping it. At the old 6px the ring ate 2px from each side
+  // and left 2px of colour: a ring with almost no dot in it.
+  dot: {
+    height: semanticTokens.spacingMd,
+    minWidth: semanticTokens.spacingMd,
+    paddingInline: 0,
+    width: semanticTokens.spacingMd,
+  },
+  info: {
+    backgroundColor: semanticTokens.statusInfoText,
+    color: semanticTokens.colorTextOnAccent,
+  },
+  success: {
+    backgroundColor: semanticTokens.statusSuccessText,
+    color: semanticTokens.colorTextOnAccent,
+  },
+  warning: {
+    backgroundColor: semanticTokens.statusWarningText,
+    color: semanticTokens.colorTextOnAccent,
+  },
+  danger: {
+    backgroundColor: semanticTokens.statusDangerText,
+    color: semanticTokens.colorTextOnAccent,
+  },
+});
+
+/** Props for a count or dot attached to another control. */
+export interface IndicatorProps extends Omit<
+  HTMLAttributes<HTMLSpanElement>,
+  'children' | 'className'
+> {
+  readonly children: ReactNode;
+  readonly count?: number;
+  readonly label: string;
+  readonly max?: number;
+  readonly tone?: StatusTone;
+}
+
+/**
+ * Attaches a count or a dot to the control it wraps. The label is what a
+ * screen reader hears, because "3" beside an icon means nothing on its own.
+ */
+export function Indicator({
+  children,
+  count,
+  label,
+  max = 99,
+  tone = 'danger',
+  ...props
+}: IndicatorProps) {
+  const showCount = count !== undefined;
+  const display = showCount && count > max ? `${max}+` : String(count ?? '');
+
+  return (
+    <span {...props} {...stylex.props(styles.anchor)}>
+      {children}
+      <span
+        aria-label={label}
+        role="status"
+        {...stylex.props(styles.badge, styles[tone], !showCount && styles.dot)}
+      >
+        {showCount ? display : null}
+      </span>
+    </span>
+  );
+}

package/src/Indicator/index.ts

@@ -0,0 +1 @@
+export {Indicator, type IndicatorProps} from './Indicator.js';

package/src/InputGroup/InputGroup.doc.ts

@@ -0,0 +1,23 @@
+import type {ComponentDoc} from '../docs/types.js';
+
+export const inputGroupDoc = {
+  name: 'InputGroup',
+  description: 'Places fixed affixes beside a control.',
+  props: [
+    {name: 'children', description: 'Supplies the control being flanked.'},
+    {
+      name: 'prefix',
+      description: 'Places a decorative affix before the control.',
+    },
+    {
+      name: 'suffix',
+      description: 'Places a decorative affix after the control.',
+    },
+  ],
+  inheritedProps: [
+    'HTMLAttributes<HTMLDivElement> except children, className, and prefix',
+  ],
+  example:
+    '<InputGroup suffix="AUD"><TextInput defaultValue="120" /></InputGroup>',
+  storyId: 'core-input-group--default',
+} satisfies ComponentDoc;

package/src/InputGroup/InputGroup.tsx

@@ -0,0 +1,73 @@
+import * as stylex from '@stylexjs/stylex';
+import type {HTMLAttributes, ReactNode} from 'react';
+
+import {semanticTokens} from '../authoring.stylex.js';
+
+const styles = stylex.create({
+  group: {
+    alignItems: 'stretch',
+    display: 'flex',
+    fontFamily: semanticTokens.fontFamilyBody,
+    gap: semanticTokens.spacingXs,
+  },
+  control: {flexGrow: 1, minWidth: 0},
+  // An affix sits at the same depth as the control it flanks, so the two read
+  // as one field rather than as a chip beside a box. Its text is an eyebrow —
+  // "AUD" or "/month" names the unit without competing with the value, and at
+  // label size it was reading as loudly as the figure it qualifies.
+  addon: {
+    alignItems: 'center',
+    backgroundColor: semanticTokens.colorSurfaceMuted,
+    borderColor: semanticTokens.borderStrong,
+    borderRadius: semanticTokens.radiusElement,
+    borderStyle: semanticTokens.borderStyle,
+    borderWidth: semanticTokens.borderWidth,
+    boxSizing: 'border-box',
+    color: semanticTokens.colorTextSecondary,
+    display: 'flex',
+    flexShrink: 0,
+    fontFamily: semanticTokens.fontFamilyHeading,
+    fontSize: semanticTokens.fontSizeXs,
+    letterSpacing: semanticTokens.letterSpacingEyebrow,
+    lineHeight: semanticTokens.lineHeightHeading,
+    minHeight: semanticTokens.sizeControlMd,
+    paddingInline: semanticTokens.spacingSm,
+  },
+});
+
+/** Props for a control flanked by fixed affixes. */
+export interface InputGroupProps extends Omit<
+  HTMLAttributes<HTMLDivElement>,
+  'children' | 'className' | 'prefix'
+> {
+  readonly children: ReactNode;
+  readonly prefix?: ReactNode;
+  readonly suffix?: ReactNode;
+}
+
+/**
+ * Places fixed text or controls beside an input. Affixes are decorative: put
+ * anything a reader must know in the field label, not here.
+ */
+export function InputGroup({
+  children,
+  prefix,
+  suffix,
+  ...props
+}: InputGroupProps) {
+  return (
+    <div {...props} {...stylex.props(styles.group)}>
+      {prefix === undefined ? null : (
+        <span aria-hidden="true" {...stylex.props(styles.addon)}>
+          {prefix}
+        </span>
+      )}
+      <span {...stylex.props(styles.control)}>{children}</span>
+      {suffix === undefined ? null : (
+        <span aria-hidden="true" {...stylex.props(styles.addon)}>
+          {suffix}
+        </span>
+      )}
+    </div>
+  );
+}

package/src/InputGroup/index.ts

@@ -0,0 +1 @@
+export {InputGroup, type InputGroupProps} from './InputGroup.js';

package/src/Item/Item.doc.ts

@@ -0,0 +1,15 @@
+import type {ComponentDoc} from '../docs/types.js';
+
+export const itemDoc = {
+  name: 'Item',
+  description:
+    'Lays out a leading slot, label, description, and trailing slot.',
+  props: [
+    {name: 'description', description: 'Adds secondary text under the label.'},
+    {name: 'leading', description: 'Places content before the label.'},
+    {name: 'trailing', description: 'Places content after the label.'},
+  ],
+  inheritedProps: ['HTMLAttributes<HTMLDivElement> except className'],
+  example: '<Item description="Updated today">Release notes</Item>',
+  storyId: 'core-item--default',
+} satisfies ComponentDoc;

package/src/Item/Item.tsx

@@ -0,0 +1,92 @@
+import * as stylex from '@stylexjs/stylex';
+import type {HTMLAttributes, ReactNode} from 'react';
+
+import {semanticTokens} from '../authoring.stylex.js';
+
+const styles = stylex.create({
+  base: {
+    alignItems: 'center',
+    display: 'flex',
+    fontFamily: semanticTokens.fontFamilyBody,
+    gap: semanticTokens.spacingSm,
+    minWidth: 0,
+  },
+  slot: {
+    alignItems: 'center',
+    color: semanticTokens.colorTextSecondary,
+    display: 'flex',
+    flexShrink: 0,
+  },
+  content: {
+    display: 'flex',
+    flexDirection: 'column',
+    flexGrow: 1,
+    minWidth: 0,
+  },
+  // Three ranks, top to bottom: the label is what the row is, the slots are
+  // what is available beside it, the description is context. Separating them
+  // by ink is what keeps a list of rows from needing a fill per row.
+  // No colour here. A row is placed inside things that have already decided
+  // what rank it holds — a disabled menu item, a second-rank option — and
+  // pinning the first rank here overrode every one of them. The label inherits
+  // its ink from whatever placed it; the description still steps down, because
+  // that step is relative to the label wherever the label landed.
+  label: {
+    fontFamily: semanticTokens.fontFamilyBody,
+    fontSize: semanticTokens.fontSizeMd,
+    letterSpacing: semanticTokens.letterSpacingBody,
+    lineHeight: semanticTokens.lineHeightBody,
+  },
+  description: {
+    // Secondary, not muted, and it cannot become muted. A row that responds to
+    // the pointer is read against the hover wash, not the bare surface, and on
+    // that composite the third rank lands at 3.81:1 in every dark theme. The
+    // gap that would clear 4.5:1 puts muted at 97-105% of secondary, which is
+    // not a third rank at all. So an interactive row has two ink ranks, and
+    // the description separates from the label by size instead.
+    color: semanticTokens.colorTextSecondary,
+    fontFamily: semanticTokens.fontFamilyBody,
+    fontSize: semanticTokens.fontSizeSm,
+    letterSpacing: semanticTokens.letterSpacingBody,
+    lineHeight: semanticTokens.lineHeightBody,
+  },
+});
+
+/** Props for the shared leading/label/trailing row layout. */
+export interface ItemProps extends Omit<
+  HTMLAttributes<HTMLDivElement>,
+  'className'
+> {
+  readonly description?: ReactNode;
+  readonly leading?: ReactNode;
+  readonly trailing?: ReactNode;
+}
+
+/**
+ * Lays out one row of content so lists, menus, and navigation share the same
+ * spacing rhythm without each re-deriving it.
+ */
+export function Item({
+  children,
+  description,
+  leading,
+  trailing,
+  ...props
+}: ItemProps) {
+  return (
+    <div {...props} {...stylex.props(styles.base)}>
+      {leading === undefined ? null : (
+        <span {...stylex.props(styles.slot)}>{leading}</span>
+      )}
+      <span {...stylex.props(styles.content)}>
+        <span {...stylex.props(styles.label)}>{children}</span>
+        {description === undefined ? null : (
+          <span {...stylex.props(styles.description)}>{description}</span>
+        )}
+      </span>
+      {trailing === undefined ? null : (
+        <span {...stylex.props(styles.slot)}>{trailing}</span>
+      )}
+    </div>
+  );
+}

package/src/Item/index.ts

@@ -0,0 +1 @@
+export {Item, type ItemProps} from './Item.js';

package/src/Kbd/Kbd.doc.ts

@@ -0,0 +1,10 @@
+import type {ComponentDoc} from '../docs/types.js';
+
+export const kbdDoc = {
+  name: 'Kbd',
+  description: 'Renders a keyboard key inside running text.',
+  props: [{name: 'children', description: 'Supplies the key label.'}],
+  inheritedProps: ['HTMLAttributes<HTMLElement> except className'],
+  example: '<Kbd>Esc</Kbd>',
+  storyId: 'core-kbd--default',
+} satisfies ComponentDoc;

package/src/Kbd/Kbd.tsx

@@ -0,0 +1,38 @@
+import * as stylex from '@stylexjs/stylex';
+import type {HTMLAttributes} from 'react';
+
+import {semanticTokens} from '../authoring.stylex.js';
+
+const styles = stylex.create({
+  base: {
+    // A key cap is a well in the page, not a bevelled object above it — and at
+    // this size not an outlined one either: a 16px box with a hairline round
+    // it reads as a field that failed to grow. The fill draws the edge.
+    backgroundColor: semanticTokens.colorSurfaceMuted,
+    borderRadius: semanticTokens.radiusInner,
+    borderStyle: 'none',
+    boxShadow: 'none',
+    color: semanticTokens.colorText,
+    display: 'inline-block',
+    fontFamily: semanticTokens.fontFamilyMono,
+    fontSize: semanticTokens.fontSizeXs,
+    fontVariantNumeric: 'tabular-nums',
+    fontWeight: semanticTokens.fontWeightMedium,
+    letterSpacing: semanticTokens.letterSpacingMono,
+    lineHeight: semanticTokens.lineHeightBody,
+    paddingInline: semanticTokens.spacingXs,
+    whiteSpace: 'nowrap',
+  },
+});
+
+/** Props for a rendered keyboard key. */
+export type KbdProps = Omit<HTMLAttributes<HTMLElement>, 'className'>;
+
+/** Renders one keyboard key so shortcuts read as input, not as prose. */
+export function Kbd({children, ...props}: KbdProps) {
+  return (
+    <kbd {...props} {...stylex.props(styles.base)}>
+      {children}
+    </kbd>
+  );
+}

package/src/Kbd/index.ts

@@ -0,0 +1 @@
+export {Kbd, type KbdProps} from './Kbd.js';

package/src/Layer/Layer.doc.ts

@@ -0,0 +1,17 @@
+import type {ComponentDoc} from '../docs/types.js';
+
+export const layerDoc = {
+  name: 'Layer',
+  description:
+    'Portals a floating surface out of the current stacking context.',
+  props: [
+    {name: 'children', description: 'Supplies the portalled content.'},
+    {
+      name: 'container',
+      description: 'Selects the portal target; defaults to the document body.',
+    },
+  ],
+  inheritedProps: ['None; Layer renders no element of its own'],
+  example: '<Layer><div role="dialog">...</div></Layer>',
+  storyId: 'core-layer--default',
+} satisfies ComponentDoc;

package/src/Layer/Layer.tsx

@@ -0,0 +1,37 @@
+import {useEffect, useState, type ReactNode} from 'react';
+import {createPortal} from 'react-dom';
+
+import {useOptionalTheme} from '../theme/Theme.js';
+
+/** Props for the portal boundary shared by every floating surface. */
+export interface LayerProps {
+  readonly children: ReactNode;
+  readonly container?: Element | null;
+}
+
+/**
+ * Renders its children outside the current DOM position so a floating surface
+ * escapes ancestor overflow and stacking contexts. Nothing is portalled during
+ * the server render, so hydration matches the markup React sent.
+ *
+ * The default target is the theme root, not `document.body`. A theme writes its
+ * custom properties onto its own element, so a surface portalled past it
+ * resolves every `var()` to nothing and renders with no background, no radius
+ * and no shadow — which is what every floating surface in this library was
+ * doing. Falling back to the body keeps a Layer working with no provider above
+ * it, which is how the primitive is used on its own.
+ */
+export function Layer({children, container}: LayerProps) {
+  const [mounted, setMounted] = useState(false);
+  const theme = useOptionalTheme();
+
+  useEffect(() => {
+    setMounted(true);
+  }, []);
+
+  if (!mounted) {
+    return null;
+  }
+
+  return createPortal(children, container ?? theme?.root ?? document.body);
+}

package/src/Layer/index.ts

@@ -0,0 +1 @@
+export {Layer, type LayerProps} from './Layer.js';

package/src/Layout/Layout.doc.ts

@@ -0,0 +1,33 @@
+import type {ComponentDoc} from '../docs/types.js';
+
+export const layoutDoc = {
+  name: 'Layout',
+  description: 'Positions banner, rails, main content, and footer.',
+  props: [
+    {name: 'aside', description: 'Places a secondary rail after the content.'},
+    {name: 'children', description: 'Supplies the main region content.'},
+    {
+      name: 'contentPadding',
+      description:
+        'Drops the main region gutter when the page supplies its own.',
+    },
+    {name: 'footer', description: 'Places content below the body.'},
+    {name: 'header', description: 'Places the banner above the body.'},
+    {name: 'mainId', description: 'Sets the id of the main element itself.'},
+    {
+      name: 'pageHead',
+      description: 'Opens the main region with a chapter head.',
+    },
+    {
+      name: 'pageIndex',
+      description: 'Hangs a numeral in the margin beside the page head.',
+    },
+    {name: 'sidebar', description: 'Places a primary rail before the content.'},
+  ],
+  inheritedProps: [
+    'HTMLAttributes<HTMLDivElement> except children and className',
+  ],
+  example:
+    '<Layout header={<TopNav />} sidebar={<SideNav>…</SideNav>}>…</Layout>',
+  storyId: 'core-layout--default',
+} satisfies ComponentDoc;