@misoto22/kioku-ui 0.0.0

package/src/Field/Field.tsx

@@ -0,0 +1,126 @@
+import * as stylex from '@stylexjs/stylex';
+import {
+  createContext,
+  useContext,
+  useId,
+  type HTMLAttributes,
+  type ReactNode,
+} from 'react';
+
+import {semanticTokens} from '../authoring.stylex.js';
+import type {StatusTone} from '../Badge/index.js';
+
+interface FieldContextValue {
+  readonly controlId: string;
+  readonly describedBy: string | undefined;
+  readonly invalid: boolean;
+  readonly required: boolean;
+}
+
+const FieldContext = createContext<FieldContextValue | null>(null);
+
+const styles = stylex.create({
+  root: {display: 'grid', gap: semanticTokens.spacingXs},
+  label: {
+    alignItems: 'baseline',
+    color: semanticTokens.colorText,
+    display: 'flex',
+    fontFamily: semanticTokens.fontFamilyBody,
+    fontSize: semanticTokens.fontSizeSm,
+    fontWeight: semanticTokens.fontWeightMedium,
+    gap: semanticTokens.spacingSm,
+    justifyContent: 'space-between',
+  },
+  annotation: {
+    color: semanticTokens.colorTextMuted,
+    fontWeight: semanticTokens.fontWeightRegular,
+  },
+  message: {
+    fontFamily: semanticTokens.fontFamilyBody,
+    fontSize: semanticTokens.fontSizeSm,
+    margin: 0,
+  },
+  description: {color: semanticTokens.colorTextSecondary},
+  info: {color: semanticTokens.statusInfoText},
+  success: {color: semanticTokens.statusSuccessText},
+  warning: {color: semanticTokens.statusWarningText},
+  danger: {color: semanticTokens.statusDangerText},
+});
+
+/** Native requirement metadata displayed alongside the field label. */
+export type FieldNecessity = 'required' | 'optional';
+
+export interface FieldProps extends Omit<
+  HTMLAttributes<HTMLDivElement>,
+  'className'
+> {
+  readonly controlId?: string;
+  readonly description?: ReactNode;
+  readonly label: ReactNode;
+  readonly necessity?: FieldNecessity;
+  readonly status?: ReactNode;
+  readonly statusTone?: StatusTone;
+}
+
+export function Field({
+  children,
+  controlId,
+  description,
+  label,
+  necessity,
+  status,
+  statusTone = 'danger',
+  ...props
+}: FieldProps) {
+  const generatedId = useId();
+  const resolvedControlId = controlId ?? `${generatedId}-control`;
+  const descriptionId = description ? `${generatedId}-description` : undefined;
+  const statusId = status ? `${generatedId}-status` : undefined;
+  const describedBy =
+    [descriptionId, statusId].filter(Boolean).join(' ') || undefined;
+
+  return (
+    <FieldContext.Provider
+      value={{
+        controlId: resolvedControlId,
+        describedBy,
+        invalid: Boolean(status && statusTone === 'danger'),
+        required: necessity === 'required',
+      }}
+    >
+      <div {...props} {...stylex.props(styles.root)}>
+        <label htmlFor={resolvedControlId} {...stylex.props(styles.label)}>
+          <span>{label}</span>
+          {necessity ? (
+            <span
+              {...stylex.props(styles.annotation)}
+            >{` (${necessity})`}</span>
+          ) : null}
+        </label>
+        {children}
+        {description ? (
+          <p
+            id={descriptionId}
+            {...stylex.props(styles.message, styles.description)}
+          >
+            {description}
+          </p>
+        ) : null}
+        {status ? (
+          <p
+            aria-live={statusTone === 'danger' ? 'assertive' : 'polite'}
+            id={statusId}
+            role={statusTone === 'danger' ? 'alert' : 'status'}
+            {...stylex.props(styles.message, styles[statusTone])}
+          >
+            {status}
+          </p>
+        ) : null}
+      </div>
+    </FieldContext.Provider>
+  );
+}
+
+export function useFieldControl() {
+  return useContext(FieldContext);
+}

package/src/Field/index.ts

@@ -0,0 +1,6 @@
+export {
+  Field,
+  useFieldControl,
+  type FieldNecessity,
+  type FieldProps,
+} from './Field.js';

package/src/Grid/Grid.doc.ts

@@ -0,0 +1,16 @@
+import type {ComponentDoc} from '../docs/types.js';
+
+export const gridDoc = {
+  name: 'Grid',
+  description: 'Arranges content in a fixed, semantic-token-spaced grid.',
+  props: [
+    {
+      name: 'columns',
+      description: 'Optional number of columns from 1 through 4.',
+    },
+    {name: 'gap', description: 'Optional semantic gap token.'},
+  ],
+  inheritedProps: ['HTMLAttributes<HTMLDivElement> except className'],
+  example: '<Grid columns={2}><Text>First</Text><Text>Second</Text></Grid>',
+  storyId: 'core-grid--default',
+} satisfies ComponentDoc;

package/src/Grid/Grid.tsx

@@ -0,0 +1,54 @@
+import * as stylex from '@stylexjs/stylex';
+import type {HTMLAttributes} from 'react';
+
+import {semanticTokens} from '../authoring.stylex.js';
+import type {Space} from '../Stack/index.js';
+
+const styles = stylex.create({
+  base: {display: 'grid'},
+  columnOne: {gridTemplateColumns: 'repeat(1, minmax(0, 1fr))'},
+  columnTwo: {gridTemplateColumns: 'repeat(2, minmax(0, 1fr))'},
+  columnThree: {gridTemplateColumns: 'repeat(3, minmax(0, 1fr))'},
+  columnFour: {gridTemplateColumns: 'repeat(4, minmax(0, 1fr))'},
+  gapXs: {gap: semanticTokens.spacingXs},
+  gapSm: {gap: semanticTokens.spacingSm},
+  gapMd: {gap: semanticTokens.spacingMd},
+  gapLg: {gap: semanticTokens.spacingLg},
+  gapXl: {gap: semanticTokens.spacingXl},
+  gap2xl: {gap: semanticTokens.spacing2xl},
+});
+
+export interface GridProps extends Omit<
+  HTMLAttributes<HTMLDivElement>,
+  'className'
+> {
+  readonly columns?: 1 | 2 | 3 | 4;
+  readonly gap?: Space;
+}
+
+const columnStyles = {
+  1: styles.columnOne,
+  2: styles.columnTwo,
+  3: styles.columnThree,
+  4: styles.columnFour,
+} as const;
+
+const gaps = {
+  xs: styles.gapXs,
+  sm: styles.gapSm,
+  md: styles.gapMd,
+  lg: styles.gapLg,
+  xl: styles.gapXl,
+  '2xl': styles.gap2xl,
+} as const;
+
+export function Grid({columns = 1, gap = 'md', children, ...props}: GridProps) {
+  return (
+    <div
+      {...props}
+      {...stylex.props(styles.base, columnStyles[columns], gaps[gap])}
+    >
+      {children}
+    </div>
+  );
+}

package/src/Grid/index.ts

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

package/src/Heading/Heading.doc.ts

@@ -0,0 +1,26 @@
+import type {ComponentDoc} from '../docs/types.js';
+
+export const headingDoc = {
+  name: 'Heading',
+  description: 'Renders a native heading at the requested document level.',
+  props: [
+    {
+      name: 'family',
+      description:
+        'Optional "interface" family, or explicit "display" family for page-level and editorial headings.',
+    },
+    {
+      name: 'level',
+      description: 'Required native heading level from 1 through 6.',
+      required: true,
+    },
+    {
+      name: 'size',
+      description:
+        'Optional semantic size: "page", "section", or "subsection".',
+    },
+  ],
+  inheritedProps: ['HTMLAttributes<HTMLHeadingElement> except className'],
+  example: '<Heading level={2} size="section">Section title</Heading>',
+  storyId: 'core-heading--default',
+} satisfies ComponentDoc;

package/src/Heading/Heading.tsx

@@ -0,0 +1,48 @@
+import * as stylex from '@stylexjs/stylex';
+import {createElement, type HTMLAttributes} from 'react';
+
+import {semanticTokens} from '../authoring.stylex.js';
+
+const styles = stylex.create({
+  base: {
+    color: semanticTokens.colorText,
+    fontFamily: semanticTokens.fontFamilyHeading,
+    fontWeight: semanticTokens.fontWeightStrong,
+    lineHeight: semanticTokens.lineHeightHeading,
+    margin: 0,
+  },
+  page: {fontSize: semanticTokens.fontSize2xl},
+  section: {fontSize: semanticTokens.fontSizeXl},
+  subsection: {fontSize: semanticTokens.fontSizeLg},
+  interface: {fontFamily: semanticTokens.fontFamilyHeading},
+  display: {
+    fontFamily: semanticTokens.fontFamilyDisplay,
+    fontSynthesis: 'none',
+  },
+});
+
+type HeadingLevel = 1 | 2 | 3 | 4 | 5 | 6;
+export type HeadingFamily = 'interface' | 'display';
+
+export interface HeadingProps extends Omit<
+  HTMLAttributes<HTMLHeadingElement>,
+  'className'
+> {
+  readonly family?: HeadingFamily;
+  readonly level: HeadingLevel;
+  readonly size?: 'page' | 'section' | 'subsection';
+}
+
+export function Heading({
+  children,
+  family = 'interface',
+  level,
+  size = 'section',
+  ...props
+}: HeadingProps) {
+  return createElement(
+    `h${level}`,
+    {...props, ...stylex.props(styles.base, styles[size], styles[family])},
+    children,
+  );
+}

package/src/Heading/index.ts

@@ -0,0 +1 @@
+export {Heading, type HeadingFamily, type HeadingProps} from './Heading.js';

package/src/IconButton/IconButton.doc.ts

@@ -0,0 +1,24 @@
+import type {ComponentDoc} from '../docs/types.js';
+
+export const iconButtonDoc = {
+  name: 'IconButton',
+  description: 'Triggers an icon-only action with a required accessible label.',
+  props: [
+    {
+      name: 'aria-label',
+      description: 'Names the icon-only action.',
+      required: true,
+    },
+    {
+      name: 'loading',
+      description: 'Shows progress and disables native activation.',
+    },
+    {name: 'size', description: 'Selects the fixed square control size.'},
+    {name: 'variant', description: 'Selects a semantic visual emphasis.'},
+  ],
+  inheritedProps: [
+    'ButtonHTMLAttributes<HTMLButtonElement> except aria-label and className',
+  ],
+  example: '<IconButton aria-label="Close"><CloseIcon /></IconButton>',
+  storyId: 'core-icon-button--default',
+} satisfies ComponentDoc;

package/src/IconButton/IconButton.tsx

@@ -0,0 +1,18 @@
+import {
+  ActionControl,
+  type ButtonProps,
+  type ButtonVariant,
+  type ControlSize,
+} from '../Button/index.js';
+
+/** Props for an icon-only native action button with a required name. */
+export interface IconButtonProps extends Omit<ButtonProps, 'aria-label'> {
+  readonly 'aria-label': string;
+  readonly loading?: boolean;
+  readonly size?: ControlSize;
+  readonly variant?: ButtonVariant;
+}
+
+export function IconButton(props: IconButtonProps) {
+  return <ActionControl {...props} iconOnly />;
+}

package/src/IconButton/index.ts

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

package/src/MetricGrid/MetricGrid.doc.ts

@@ -0,0 +1,19 @@
+import type {ComponentDoc} from '../docs/types.js';
+
+export const metricGridDoc = {
+  name: 'MetricGrid',
+  description:
+    'Presents consumer-supplied labels and values with responsive description-list hierarchy.',
+  props: [
+    {
+      name: 'items',
+      description: 'Supplies metric labels, values, and optional detail.',
+      required: true,
+    },
+  ],
+  inheritedProps: [
+    'HTMLAttributes<HTMLDListElement> except children and className',
+  ],
+  example: '<MetricGrid items={[{label: "Total", value: "24"}]} />',
+  storyId: 'core-metric-grid--default',
+} satisfies ComponentDoc;

package/src/MetricGrid/MetricGrid.tsx

@@ -0,0 +1,72 @@
+import * as stylex from '@stylexjs/stylex';
+import type {HTMLAttributes, ReactNode} from 'react';
+
+import {semanticTokens} from '../authoring.stylex.js';
+
+const minimumColumnWidth = `calc(${semanticTokens.spacing2xl} + ${semanticTokens.spacing2xl} + ${semanticTokens.spacing2xl} + ${semanticTokens.spacing2xl} + ${semanticTokens.spacing2xl} + ${semanticTokens.spacing2xl} + ${semanticTokens.spacing2xl} + ${semanticTokens.spacing2xl})`;
+
+const styles = stylex.create({
+  root: {
+    display: 'grid',
+    gap: semanticTokens.spacingLg,
+    gridTemplateColumns: `repeat(auto-fit, minmax(min(100%, ${minimumColumnWidth}), 1fr))`,
+    margin: 0,
+  },
+  item: {
+    backgroundColor: semanticTokens.colorSurface,
+    borderColor: semanticTokens.borderDefault,
+    borderRadius: semanticTokens.radiusContainer,
+    borderStyle: semanticTokens.borderStyle,
+    borderWidth: semanticTokens.borderWidth,
+    display: 'grid',
+    gap: semanticTokens.spacingXs,
+    padding: semanticTokens.spacingLg,
+  },
+  label: {
+    color: semanticTokens.colorTextSecondary,
+    fontFamily: semanticTokens.fontFamilyBody,
+    fontSize: semanticTokens.fontSizeSm,
+  },
+  value: {
+    color: semanticTokens.colorText,
+    fontFamily: semanticTokens.fontFamilyHeading,
+    fontSize: semanticTokens.fontSizeXl,
+    fontWeight: semanticTokens.fontWeightStrong,
+    margin: 0,
+  },
+  detail: {
+    color: semanticTokens.colorTextMuted,
+    fontFamily: semanticTokens.fontFamilyBody,
+    fontSize: semanticTokens.fontSizeSm,
+    margin: 0,
+  },
+});
+
+export interface MetricGridItem {
+  readonly detail?: ReactNode;
+  readonly label: ReactNode;
+  readonly value: ReactNode;
+}
+
+export interface MetricGridProps extends Omit<
+  HTMLAttributes<HTMLDListElement>,
+  'children' | 'className'
+> {
+  readonly items: readonly MetricGridItem[];
+}
+
+export function MetricGrid({items, ...props}: MetricGridProps) {
+  return (
+    <dl {...props} {...stylex.props(styles.root)}>
+      {items.map((item, index) => (
+        <div key={index} {...stylex.props(styles.item)}>
+          <dt {...stylex.props(styles.label)}>{item.label}</dt>
+          <dd {...stylex.props(styles.value)}>{item.value}</dd>
+          {item.detail ? (
+            <dd {...stylex.props(styles.detail)}>{item.detail}</dd>
+          ) : null}
+        </div>
+      ))}
+    </dl>
+  );
+}

package/src/MetricGrid/index.ts

@@ -0,0 +1,5 @@
+export {
+  MetricGrid,
+  type MetricGridItem,
+  type MetricGridProps,
+} from './MetricGrid.js';

package/src/Section/Section.doc.ts

@@ -0,0 +1,12 @@
+import type {ComponentDoc} from '../docs/types.js';
+
+export const sectionDoc = {
+  name: 'Section',
+  description: 'Groups related content in a native section landmark.',
+  props: [
+    {name: 'padding', description: 'Optional semantic block-padding token.'},
+  ],
+  inheritedProps: ['HTMLAttributes<HTMLElement> except className'],
+  example: '<Section aria-label="Preferences"><Text>Content</Text></Section>',
+  storyId: 'core-section--default',
+} satisfies ComponentDoc;

package/src/Section/Section.tsx

@@ -0,0 +1,38 @@
+import * as stylex from '@stylexjs/stylex';
+import type {HTMLAttributes} from 'react';
+
+import {semanticTokens} from '../authoring.stylex.js';
+import type {Space} from '../Stack/index.js';
+
+const styles = stylex.create({
+  paddingXs: {paddingBlock: semanticTokens.spacingXs},
+  paddingSm: {paddingBlock: semanticTokens.spacingSm},
+  paddingMd: {paddingBlock: semanticTokens.spacingMd},
+  paddingLg: {paddingBlock: semanticTokens.spacingLg},
+  paddingXl: {paddingBlock: semanticTokens.spacingXl},
+  padding2xl: {paddingBlock: semanticTokens.spacing2xl},
+});
+
+const paddings = {
+  xs: styles.paddingXs,
+  sm: styles.paddingSm,
+  md: styles.paddingMd,
+  lg: styles.paddingLg,
+  xl: styles.paddingXl,
+  '2xl': styles.padding2xl,
+} as const;
+
+export interface SectionProps extends Omit<
+  HTMLAttributes<HTMLElement>,
+  'className'
+> {
+  readonly padding?: Space;
+}
+
+export function Section({children, padding = 'xl', ...props}: SectionProps) {
+  return (
+    <section {...props} {...stylex.props(paddings[padding])}>
+      {children}
+    </section>
+  );
+}

package/src/Section/index.ts

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

package/src/SegmentedControl/SegmentedControl.doc.ts

@@ -0,0 +1,51 @@
+import type {ComponentDoc} from '../docs/types.js';
+
+export const segmentedControlDoc = {
+  name: 'SegmentedControl',
+  description:
+    'Chooses one supplied option with roving radio-group keyboard behavior.',
+  props: [
+    {
+      name: 'aria-label',
+      description:
+        'Directly names the radiogroup when no external label is used.',
+    },
+    {
+      name: 'aria-labelledby',
+      description: 'References the element that names the radiogroup.',
+    },
+    {
+      name: 'defaultValue',
+      description:
+        'Sets the initial value for uncontrolled selection while preserving roving focus.',
+    },
+    {
+      name: 'disabled',
+      description:
+        'Disables every option and removes the group from tab order.',
+    },
+    {
+      name: 'onValueChange',
+      description: 'Receives the next value selected by pointer or keyboard.',
+    },
+    {
+      name: 'options',
+      description: 'Supplies labels, values, and disabled states.',
+      required: true,
+    },
+    {
+      name: 'orientation',
+      description: 'Selects horizontal or vertical arrow-key behavior.',
+    },
+    {
+      name: 'value',
+      description:
+        'Controls the current selected value; pointer and keyboard intent is reported through onValueChange.',
+    },
+  ],
+  inheritedProps: [
+    'HTMLAttributes<HTMLDivElement> except aria-label, aria-labelledby, className, defaultValue, and onChange',
+  ],
+  example: '<SegmentedControl aria-label="Alignment" options={options} />',
+  storyId: 'core-segmented-control--default',
+} satisfies ComponentDoc;