@misoto22/kioku-ui 0.0.0 → 0.2.0

package/src/PowerSearch/PowerSearch.tsx

@@ -0,0 +1,235 @@
+import * as stylex from '@stylexjs/stylex';
+import {
+  useState,
+  type FormEvent,
+  type HTMLAttributes,
+  type ReactNode,
+} from 'react';
+
+import {semanticTokens} from '../authoring.stylex.js';
+import {Button} from '../Button/index.js';
+import {Icon} from '../Icon/index.js';
+import {Token} from '../Token/index.js';
+
+const styles = stylex.create({
+  form: {
+    display: 'grid',
+    fontFamily: semanticTokens.fontFamilyBody,
+    gap: semanticTokens.spacingSm,
+  },
+  row: {
+    alignItems: 'center',
+    display: 'flex',
+    gap: semanticTokens.spacingSm,
+  },
+  // The glass and the query are one line of text with a well drawn round it,
+  // so they are separated by the same step that separates any icon from the
+  // word beside it — not by the hairline step used inside a token.
+  field: {
+    alignItems: 'center',
+    backgroundColor: semanticTokens.colorSurfaceMuted,
+    borderColor: semanticTokens.borderStrong,
+    borderRadius: semanticTokens.radiusElement,
+    borderStyle: semanticTokens.borderStyle,
+    borderWidth: semanticTokens.borderWidth,
+    boxSizing: 'border-box',
+    display: 'flex',
+    flexGrow: 1,
+    gap: semanticTokens.spacingSm,
+    minHeight: semanticTokens.sizeControlMd,
+    paddingBlock: semanticTokens.spacingXs,
+    paddingInline: semanticTokens.spacingSm,
+    transitionDuration: semanticTokens.durationFast,
+    transitionProperty: 'border-color',
+    transitionTimingFunction: semanticTokens.easingStandard,
+    ':hover': {borderColor: semanticTokens.borderInteractive},
+    // Same reason as `Tokenizer`: the well spends 3px of block padding and the
+    // ring needs 4px, so drawn on the field inside it the well clipped it.
+    ':focus-within': {
+      borderColor: semanticTokens.borderInteractive,
+      outlineColor: semanticTokens.colorFocus,
+      outlineOffset: semanticTokens.focusOffset,
+      outlineStyle: semanticTokens.borderStyle,
+      outlineWidth: semanticTokens.focusWidth,
+    },
+  },
+  input: {
+    backgroundColor: 'transparent',
+    borderStyle: 'none',
+    borderWidth: 0,
+    color: semanticTokens.colorText,
+    flexGrow: 1,
+    fontFamily: semanticTokens.fontFamilyBody,
+    fontSize: semanticTokens.fontSizeMd,
+    letterSpacing: semanticTokens.letterSpacingBody,
+    lineHeight: semanticTokens.lineHeightBody,
+    minWidth: 0,
+    padding: 0,
+    // WebKit grows its own cancel cross inside a search field. The filters
+    // directly beneath this row are drawn by `Token`, down to the hit target
+    // on their remove control — one engine-drawn cross in the middle of them
+    // is the only mark on this component nobody chose.
+    '::-webkit-search-cancel-button': {appearance: 'none'},
+    '::placeholder': {color: semanticTokens.colorTextMuted},
+    ':focus-visible': {outlineStyle: 'none'},
+  },
+  // The same recipe `Token` uses for its remove control, because it is the
+  // same gesture one line higher up: a visual box that tracks the type and a
+  // reachable box that stays a full target.
+  clear: {
+    alignItems: 'center',
+    backgroundColor: 'transparent',
+    borderRadius: semanticTokens.radiusInner,
+    borderStyle: 'none',
+    borderWidth: 0,
+    color: semanticTokens.colorTextSecondary,
+    cursor: 'pointer',
+    display: 'inline-flex',
+    flexShrink: 0,
+    padding: 0,
+    position: 'relative',
+    transitionDuration: semanticTokens.durationFast,
+    transitionProperty: 'color',
+    transitionTimingFunction: semanticTokens.easingStandard,
+    '::before': {
+      content: '',
+      height: semanticTokens.sizeHitTarget,
+      insetBlockStart: '50%',
+      insetInlineStart: '50%',
+      position: 'absolute',
+      transform: 'translate(-50%, -50%)',
+      width: semanticTokens.sizeHitTarget,
+    },
+    ':focus-visible': {
+      outlineColor: semanticTokens.colorFocus,
+      outlineOffset: semanticTokens.focusOffset,
+      outlineStyle: semanticTokens.borderStyle,
+      outlineWidth: semanticTokens.focusWidth,
+    },
+    ':hover:not(:disabled)': {color: semanticTokens.colorText},
+  },
+  filters: {
+    display: 'flex',
+    flexWrap: 'wrap',
+    gap: semanticTokens.spacingSm,
+    listStyleType: 'none',
+    marginBlock: 0,
+    paddingInlineStart: 0,
+  },
+});
+
+/** One applied search filter. */
+export interface SearchFilter {
+  readonly id: string;
+  readonly label: string;
+}
+
+/** Props for a search field that carries applied filters. */
+export interface PowerSearchProps extends Omit<
+  HTMLAttributes<HTMLFormElement>,
+  'children' | 'className' | 'onSubmit' | 'role'
+> {
+  readonly filters?: readonly SearchFilter[];
+  readonly label: string;
+  readonly onFiltersChange?: (filters: readonly SearchFilter[]) => void;
+  readonly onSearch: (query: string) => void;
+  readonly clearLabel?: string;
+  readonly placeholder?: string;
+  readonly submitLabel?: ReactNode;
+}
+
+/**
+ * Searches with the filters already applied shown beside the query, so a
+ * reader can see and undo each narrowing rather than wondering why a result
+ * set looks short.
+ */
+export function PowerSearch({
+  clearLabel = 'Clear search',
+  filters = [],
+  label,
+  onFiltersChange,
+  onSearch,
+  placeholder,
+  submitLabel = 'Search',
+  ...props
+}: PowerSearchProps) {
+  const [query, setQuery] = useState('');
+
+  function handleSubmit(event: FormEvent<HTMLFormElement>) {
+    event.preventDefault();
+    onSearch(query);
+  }
+
+  return (
+    <form
+      {...props}
+      onSubmit={handleSubmit}
+      role="search"
+      {...stylex.props(styles.form)}
+    >
+      <div {...stylex.props(styles.row)}>
+        <div {...stylex.props(styles.field)}>
+          {/* Sized off the type scale rather than an inherited em, so the
+              glass keeps its proportion to the query at any density. */}
+          <Icon size="md" tone="muted">
+            <path
+              d="M11 4a7 7 0 1 0 0 14 7 7 0 0 0 0-14Zm5 12 4 4"
+              fill="none"
+              stroke="currentColor"
+              strokeWidth="2"
+            />
+          </Icon>
+          <input
+            aria-label={label}
+            onChange={(event) => {
+              setQuery(event.currentTarget.value);
+            }}
+            placeholder={placeholder}
+            value={query}
+            {...stylex.props(styles.input)}
+            type="search"
+          />
+          {query === '' ? null : (
+            <button
+              aria-label={clearLabel}
+              onClick={() => {
+                setQuery('');
+              }}
+              type="button"
+              {...stylex.props(styles.clear)}
+            >
+              <Icon size="sm" tone="inherit">
+                <path
+                  d="M6 6 18 18M18 6 6 18"
+                  fill="none"
+                  stroke="currentColor"
+                  strokeLinecap="round"
+                  strokeWidth="2"
+                />
+              </Icon>
+            </button>
+          )}
+        </div>
+        <Button type="submit">{submitLabel}</Button>
+      </div>
+      {filters.length === 0 ? null : (
+        <ul {...stylex.props(styles.filters)}>
+          {filters.map((filter) => (
+            <li key={filter.id}>
+              <Token
+                onRemove={() => {
+                  onFiltersChange?.(
+                    filters.filter((entry) => entry.id !== filter.id),
+                  );
+                }}
+                removeLabel={`Remove filter ${filter.label}`}
+              >
+                {filter.label}
+              </Token>
+            </li>
+          ))}
+        </ul>
+      )}
+    </form>
+  );
+}

package/src/PowerSearch/index.ts

@@ -0,0 +1,5 @@
+export {
+  PowerSearch,
+  type PowerSearchProps,
+  type SearchFilter,
+} from './PowerSearch.js';

package/src/ProgressBar/ProgressBar.doc.ts

@@ -0,0 +1,16 @@
+import type {ComponentDoc} from '../docs/types.js';
+
+export const progressBarDoc = {
+  name: 'ProgressBar',
+  description: 'Reports how far a task has run.',
+  props: [
+    {name: 'label', description: 'Names what is progressing.'},
+    {name: 'max', description: 'Sets the value that counts as complete.'},
+    {name: 'value', description: 'Sets progress so far; omit when unknown.'},
+  ],
+  inheritedProps: [
+    'HTMLAttributes<HTMLDivElement> except aria-label, aria-valuemax, aria-valuemin, aria-valuenow, children, className, and role',
+  ],
+  example: '<ProgressBar label="Uploading" value={40} />',
+  storyId: 'core-progress-bar--default',
+} satisfies ComponentDoc;

package/src/ProgressBar/ProgressBar.tsx

@@ -0,0 +1,98 @@
+import * as stylex from '@stylexjs/stylex';
+import type {HTMLAttributes} from 'react';
+
+import {semanticTokens} from '../authoring.stylex.js';
+
+// Carries the stub of an unknown-length task across its track: from just
+// off the leading edge to just past the trailing one.
+const sweep = stylex.keyframes({
+  from: {transform: 'translateX(-100%)'},
+  to: {transform: 'translateX(250%)'},
+});
+
+const styles = stylex.create({
+  track: {
+    backgroundColor: semanticTokens.colorSurfaceMuted,
+    borderRadius: semanticTokens.radiusFull,
+    display: 'block',
+    height: semanticTokens.spacingSm,
+    overflow: 'hidden',
+    width: '100%',
+  },
+  // The track at rest is the well; the part that has been earned is full ink.
+  // The accent's jobs are the focus ring, the selected mark and a link on
+  // hover, and a bar filling half a track is none of the three — the same
+  // reasoning the spinner's moving arc is drawn by.
+  fill: {
+    backgroundColor: semanticTokens.colorText,
+    borderRadius: semanticTokens.radiusFull,
+    display: 'block',
+    height: '100%',
+    transitionDuration: semanticTokens.durationModerate,
+    transitionProperty: 'inline-size',
+    transitionTimingFunction: semanticTokens.easingStandard,
+  },
+  indeterminate: {
+    animationDuration: semanticTokens.durationSlow,
+    animationIterationCount: 'infinite',
+    animationName: {
+      default: sweep,
+      '@media (prefers-reduced-motion: reduce)': 'none',
+    },
+    animationTimingFunction: semanticTokens.easingStandard,
+    inlineSize: '40%',
+  },
+});
+
+/** Props for a determinate or indeterminate progress track. */
+export interface ProgressBarProps extends Omit<
+  HTMLAttributes<HTMLDivElement>,
+  | 'aria-label'
+  | 'aria-valuemax'
+  | 'aria-valuemin'
+  | 'aria-valuenow'
+  | 'children'
+  | 'className'
+  | 'role'
+> {
+  readonly label: string;
+  readonly max?: number;
+  readonly value?: number;
+}
+
+/**
+ * Reports how far a task has run. Omitting `value` reports work of unknown
+ * length, which a screen reader announces as busy rather than as a percentage.
+ */
+export function ProgressBar({
+  label,
+  max = 100,
+  value,
+  ...props
+}: ProgressBarProps) {
+  const determinate = value !== undefined;
+  const clamped = determinate ? Math.min(Math.max(value, 0), max) : undefined;
+
+  return (
+    <div
+      {...props}
+      aria-label={label}
+      aria-valuemax={max}
+      aria-valuemin={0}
+      {...(clamped === undefined ? {} : {'aria-valuenow': clamped})}
+      role="progressbar"
+      {...stylex.props(styles.track)}
+    >
+      <span
+        {...stylex.props(styles.fill, !determinate && styles.indeterminate)}
+        // The width is data, so it stays inline — after stylex.props, which
+        // would otherwise overwrite the style attribute it is carried in.
+        style={
+          clamped === undefined
+            ? undefined
+            : {inlineSize: `${(clamped / max) * 100}%`}
+        }
+      />
+    </div>
+  );
+}

package/src/ProgressBar/index.ts

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

package/src/RadioList/RadioList.doc.ts

@@ -0,0 +1,22 @@
+import type {ComponentDoc} from '../docs/types.js';
+
+export const radioListDoc = {
+  name: 'RadioList',
+  description: 'Offers a set of mutually exclusive choices.',
+  props: [
+    {
+      name: 'defaultValue',
+      description: 'Sets the initial uncontrolled choice.',
+    },
+    {name: 'legend', description: 'States the question the options answer.'},
+    {name: 'onValueChange', description: 'Receives the newly chosen value.'},
+    {name: 'options', description: 'Supplies the choices in reading order.'},
+    {name: 'value', description: 'Controls the current choice.'},
+  ],
+  inheritedProps: [
+    'HTMLAttributes<HTMLFieldSetElement> except children, className, defaultValue, and onChange',
+  ],
+  example:
+    '<RadioList legend="Visibility" onValueChange={setScope} options={scopes} value={scope} />',
+  storyId: 'core-radio-list--default',
+} satisfies ComponentDoc;

package/src/RadioList/RadioList.tsx

@@ -0,0 +1,244 @@
+import * as stylex from '@stylexjs/stylex';
+import {useId, useState, type HTMLAttributes, type ReactNode} from 'react';
+
+import {semanticTokens} from '../authoring.stylex.js';
+
+// The same block and the same centring `CheckboxInput` uses: one micro-control
+// tall, sitting on the first line of its label rather than on the label's whole
+// box, so a radio and a checkbox in the same form line up and a wrapped label
+// does not drag the dot downwards. Written as a relationship so a density
+// change carries both.
+const dotSize = semanticTokens.spacingLg;
+const dotFirstLineOffset = `calc((${semanticTokens.fontSizeMd} * ${semanticTokens.lineHeightBody} - ${dotSize}) / 2)`;
+
+const styles = stylex.create({
+  group: {
+    borderStyle: 'none',
+    borderWidth: 0,
+    display: 'flex',
+    flexDirection: 'column',
+    fontFamily: semanticTokens.fontFamilyBody,
+    gap: semanticTokens.spacingSm,
+    margin: 0,
+    padding: 0,
+  },
+  // The question above the answers, set as the same eyebrow `Field` gives its
+  // label: a legend and a field label do one job, and a form that mixes the
+  // two sizes reads as two forms.
+  legend: {
+    color: semanticTokens.colorTextSecondary,
+    fontFamily: semanticTokens.fontFamilyHeading,
+    fontSize: semanticTokens.fontSizeXs,
+    fontWeight: semanticTokens.fontWeightMedium,
+    letterSpacing: semanticTokens.letterSpacingEyebrow,
+    lineHeight: semanticTokens.lineHeightHeading,
+    // A legend is not a flex item: the browser lifts it out of the fieldset's
+    // formatting context and draws it in the border box, so the group's `gap`
+    // never reaches it and the first row sat flush against the question. The
+    // step has to be spent here, and it has to match the group's own gap.
+    marginBlockEnd: semanticTokens.spacingSm,
+    padding: 0,
+  },
+  row: {
+    alignItems: 'flex-start',
+    display: 'flex',
+    gap: semanticTokens.spacingSm,
+  },
+  // One answer out of several, so the mark is a filled centre rather than the
+  // tick a checkbox draws. Sized as a fraction of the well so it follows a
+  // density change with it.
+  dotChosen: {
+    '::before': {
+      backgroundColor: semanticTokens.colorText,
+      blockSize: '50%',
+      borderRadius: semanticTokens.radiusFull,
+      content: '',
+      inlineSize: '50%',
+      insetBlockStart: '50%',
+      insetInlineStart: '50%',
+      position: 'absolute',
+      transform: 'translate(-50%, -50%)',
+    },
+  },
+  dotChosenDisabled: {
+    '::before': {backgroundColor: semanticTokens.colorDisabledText},
+  },
+  // Drawn here, not by the engine — the same move `CheckboxInput` makes, and
+  // for the same reason: left native this contributed `accent-color` and took
+  // the white fill, the grey edge and every disabled tone from the browser,
+  // none of which are in this system. It is still a real radio: the click
+  // target, the group behaviour, the arrow keys and the form value stay.
+  dot: {
+    appearance: 'none',
+    backgroundColor: semanticTokens.colorSurfaceMuted,
+    blockSize: dotSize,
+    borderColor: semanticTokens.borderStrong,
+    borderRadius: semanticTokens.radiusFull,
+    borderStyle: semanticTokens.borderStyle,
+    borderWidth: semanticTokens.borderWidth,
+    boxSizing: 'border-box',
+    cursor: 'pointer',
+    display: 'inline-block',
+    flexShrink: 0,
+    inlineSize: dotSize,
+    marginBlockEnd: 0,
+    marginBlockStart: dotFirstLineOffset,
+    marginInline: 0,
+    position: 'relative',
+    transitionDuration: semanticTokens.durationFast,
+    transitionProperty: 'background-color, border-color',
+    transitionTimingFunction: semanticTokens.easingStandard,
+    ':disabled': {
+      backgroundColor: semanticTokens.colorDisabledSurface,
+      borderColor: semanticTokens.borderDisabled,
+      cursor: 'default',
+    },
+    ':hover:not(:disabled)': {borderColor: semanticTokens.borderInteractive},
+    ':focus-visible': {
+      outlineColor: semanticTokens.colorFocus,
+      outlineOffset: semanticTokens.focusOffset,
+      outlineStyle: semanticTokens.borderStyle,
+      outlineWidth: semanticTokens.focusWidth,
+    },
+  },
+  text: {
+    display: 'flex',
+    flexDirection: 'column',
+    gap: semanticTokens.spacingXs,
+  },
+  label: {
+    fontFamily: semanticTokens.fontFamilyBody,
+    fontSize: semanticTokens.fontSizeMd,
+    letterSpacing: semanticTokens.letterSpacingLabel,
+    lineHeight: semanticTokens.lineHeightBody,
+    transitionDuration: semanticTokens.durationFast,
+    transitionProperty: 'color',
+    transitionTimingFunction: semanticTokens.easingStandard,
+  },
+  // The answer that holds is marked in ink and weight, never filled.
+  labelChosen: {
+    color: semanticTokens.colorText,
+    fontWeight: semanticTokens.fontWeightMedium,
+  },
+  labelClear: {
+    color: semanticTokens.colorTextSecondary,
+    fontWeight: semanticTokens.fontWeightRegular,
+  },
+  labelDisabled: {
+    color: semanticTokens.colorDisabledText,
+    fontWeight: semanticTokens.fontWeightRegular,
+  },
+  description: {
+    color: semanticTokens.colorTextMuted,
+    fontFamily: semanticTokens.fontFamilyBody,
+    fontSize: semanticTokens.fontSizeSm,
+    letterSpacing: semanticTokens.letterSpacingBody,
+    lineHeight: semanticTokens.lineHeightBody,
+  },
+  descriptionDisabled: {color: semanticTokens.colorDisabledText},
+});
+
+/** One mutually exclusive choice. */
+export interface RadioOption {
+  readonly description?: ReactNode;
+  readonly disabled?: boolean;
+  readonly label: ReactNode;
+  readonly value: string;
+}
+
+type SharedRadioListProps = Omit<
+  HTMLAttributes<HTMLFieldSetElement>,
+  'children' | 'className' | 'defaultValue' | 'onChange'
+> & {
+  readonly legend: ReactNode;
+  readonly onValueChange?: (value: string) => void;
+  readonly options: readonly RadioOption[];
+};
+
+type ControlledRadioListProps = SharedRadioListProps & {
+  readonly defaultValue?: never;
+  readonly onValueChange: (value: string) => void;
+  readonly value: string;
+};
+
+type UncontrolledRadioListProps = SharedRadioListProps & {
+  readonly defaultValue?: string;
+  readonly value?: never;
+};
+
+/** Props for a set of mutually exclusive choices. */
+export type RadioListProps =
+  ControlledRadioListProps | UncontrolledRadioListProps;
+
+/**
+ * Offers mutually exclusive choices. It emits a `fieldset` with a `legend`, so
+ * assistive technology announces the question before the answers.
+ */
+export function RadioList({
+  defaultValue,
+  legend,
+  onValueChange,
+  options,
+  value,
+  ...props
+}: RadioListProps) {
+  const name = useId();
+  const [internalValue, setInternalValue] = useState(defaultValue ?? '');
+  const selected = value ?? internalValue;
+
+  return (
+    <fieldset {...props} {...stylex.props(styles.group)}>
+      <legend {...stylex.props(styles.legend)}>{legend}</legend>
+      {options.map(({description, disabled, label, value: optionValue}) => {
+        const isChosen = selected === optionValue;
+
+        return (
+          <label key={optionValue} {...stylex.props(styles.row)}>
+            <input
+              checked={isChosen}
+              disabled={disabled ?? false}
+              name={name}
+              onChange={() => {
+                if (value === undefined) {
+                  setInternalValue(optionValue);
+                }
+                onValueChange?.(optionValue);
+              }}
+              value={optionValue}
+              {...stylex.props(
+                styles.dot,
+                isChosen && styles.dotChosen,
+                isChosen && disabled && styles.dotChosenDisabled,
+              )}
+              type="radio"
+            />
+            <span {...stylex.props(styles.text)}>
+              <span
+                {...stylex.props(
+                  styles.label,
+                  disabled
+                    ? styles.labelDisabled
+                    : isChosen
+                      ? styles.labelChosen
+                      : styles.labelClear,
+                )}
+              >
+                {label}
+              </span>
+              {description === undefined ? null : (
+                <span
+                  {...stylex.props(
+                    styles.description,
+                    disabled && styles.descriptionDisabled,
+                  )}
+                >
+                  {description}
+                </span>
+              )}
+            </span>
+          </label>
+        );
+      })}
+    </fieldset>
+  );
+}

package/src/RadioList/index.ts

@@ -0,0 +1 @@
+export {RadioList, type RadioListProps, type RadioOption} from './RadioList.js';

package/src/Resizable/Resizable.doc.ts

@@ -0,0 +1,24 @@
+import type {ComponentDoc} from '../docs/types.js';
+
+export const resizableDoc = {
+  name: 'Resizable',
+  description: 'Splits a region into a sized panel and the rest.',
+  props: [
+    {name: 'children', description: 'Supplies the content beside the panel.'},
+    {name: 'handleLabel', description: 'Names the divider control.'},
+    {name: 'max', description: 'Caps how wide the panel can grow.'},
+    {name: 'min', description: 'Sets how narrow the panel can shrink.'},
+    {name: 'onSizeChange', description: 'Receives the next panel width.'},
+    {name: 'panel', description: 'Supplies the sized panel content.'},
+    {name: 'size', description: 'Controls the panel width in pixels.'},
+    {
+      name: 'step',
+      description: 'Sets how far each arrow key moves the divider.',
+    },
+  ],
+  inheritedProps: [
+    'HTMLAttributes<HTMLDivElement> except children and className',
+  ],
+  example: '<Resizable panel={<SideNav>…</SideNav>}>{page}</Resizable>',
+  storyId: 'core-resizable--default',
+} satisfies ComponentDoc;