@alfakit/react 0.0.0-stage → 0.1.1

package/src/components/fields/checkbox-list.tsx

@@ -0,0 +1,181 @@
+import type { CheckboxListSchema } from '@alfakit/core'
+import { fieldIds, gridColumnsClasses, htmlLabelToText, isOptionGroup } from '@alfakit/core'
+import { useEffect, useMemo, useState } from 'react'
+import { useT } from '../../context'
+import { textColorClasses } from '../../lib/colors'
+import { Icon } from '../../lib/icons'
+import { cn } from '../../lib/utils'
+import { useField } from '../form/form-context'
+import { FieldWrapper } from '../schema/field-wrapper'
+import { Button } from '../ui/button'
+import { Checkbox } from '../ui/checkbox'
+import { Input } from '../ui/input'
+import { Label } from '../ui/label'
+
+/**
+ * `gridDirection('column')`: options flow down each column (CSS columns). Classes are
+ * spelled out so Tailwind generates them.
+ */
+const COLUMN_FLOW_CLASSES: Record<number, string> = {
+  2: 'md:columns-2',
+  3: 'md:columns-3',
+  4: 'md:columns-4',
+  5: 'md:columns-5',
+  6: 'md:columns-6',
+}
+
+export function CheckboxListField({ component }: { component: CheckboxListSchema }) {
+  const t = useT()
+  const { value, setValue, error, id, disabled, readOnly, aria } = useField<Array<
+    string | number
+  > | null>(component)
+  const [search, setSearch] = useState('')
+  // `searchDebounce()`: the list is filtered by `query`, which trails the input.
+  const [debounced, setDebounced] = useState('')
+  const query = component.searchDebounce ? debounced : search
+  const locked = disabled || readOnly
+
+  const selected = useMemo(() => (value ?? []).map(String), [value])
+  const options = useMemo(
+    () =>
+      component.options.flatMap((option) => (isOptionGroup(option) ? option.options : [option])),
+    [component.options],
+  )
+  const visible = options.filter((option) =>
+    (component.allowHtml ? htmlLabelToText(option.label) : option.label)
+      .toLowerCase()
+      .includes(query.toLowerCase()),
+  )
+
+  useEffect(() => {
+    if (!component.searchDebounce) return
+
+    const timer = setTimeout(() => setDebounced(search), component.searchDebounce)
+
+    return () => clearTimeout(timer)
+  }, [search, component.searchDebounce])
+  const columnFlow = component.gridDirection === 'column' && (component.gridColumns ?? 1) > 1
+  const selectAll = component.selectAllAction
+  const deselectAll = component.deselectAllAction
+
+  const toggle = (key: string, checked: boolean) => {
+    setValue(checked ? [...selected, key] : selected.filter((item) => item !== key))
+  }
+
+  return (
+    <FieldWrapper field={component} htmlFor={id} error={error}>
+      <div className="flex flex-col gap-2">
+        {(component.searchable || (component.bulkToggleable && !readOnly)) && (
+          <div className="flex items-center gap-2">
+            {component.searchable && (
+              <Input
+                value={search}
+                onChange={(event) => setSearch(event.target.value)}
+                placeholder={component.searchPrompt ?? t('search', {}, 'Search')}
+                aria-label={component.searchPrompt ?? t('search', {}, 'Search')}
+                className="h-8"
+              />
+            )}
+            {component.bulkToggleable && !readOnly && (
+              <div className="flex gap-1">
+                {!selectAll?.hidden && (
+                  <Button
+                    type="button"
+                    variant="link"
+                    size="sm"
+                    data-slot="select-all"
+                    disabled={disabled}
+                    onClick={() =>
+                      setValue(
+                        options.filter((option) => !option.disabled).map((option) => option.value),
+                      )
+                    }
+                  >
+                    {selectAll?.icon && <Icon name={selectAll.icon} />}
+                    {selectAll?.label ?? t('table.select_all', {}, 'Select all')}
+                  </Button>
+                )}
+                {!deselectAll?.hidden && (
+                  <Button
+                    type="button"
+                    variant="link"
+                    size="sm"
+                    data-slot="deselect-all"
+                    disabled={disabled}
+                    onClick={() => setValue([])}
+                  >
+                    {deselectAll?.icon && <Icon name={deselectAll.icon} />}
+                    {deselectAll?.label ?? t('table.deselect_all', {}, 'Deselect all')}
+                  </Button>
+                )}
+              </div>
+            )}
+          </div>
+        )}
+        <div
+          data-grid-direction={component.gridDirection}
+          className={cn(
+            component.inline
+              ? 'flex flex-wrap gap-4'
+              : columnFlow
+                ? cn(
+                    'gap-x-3 *:mb-3 *:break-inside-avoid',
+                    COLUMN_FLOW_CLASSES[component.gridColumns ?? 1],
+                  )
+                : 'grid gap-3',
+            !component.inline &&
+              !columnFlow &&
+              gridColumnsClasses(
+                component.gridColumns ? { default: 1, md: component.gridColumns } : { default: 1 },
+              ),
+          )}
+          role="group"
+          aria-labelledby={component.label ? fieldIds(id).label : undefined}
+          aria-describedby={aria['aria-describedby']}
+        >
+          {visible.map((option) => {
+            const optionId = `${id}-${option.value}`
+
+            return (
+              <div key={option.value} className="flex items-start gap-2">
+                <Checkbox
+                  id={optionId}
+                  checked={selected.includes(option.value)}
+                  disabled={locked || option.disabled}
+                  onCheckedChange={(checked) => toggle(option.value, checked === true)}
+                  aria-invalid={aria['aria-invalid']}
+                  className="mt-0.5"
+                />
+                <div className="grid gap-0.5">
+                  <Label
+                    htmlFor={optionId}
+                    className={cn('font-normal', option.color && textColorClasses[option.color])}
+                  >
+                    {option.icon && <Icon name={option.icon} className="size-4" />}
+                    {component.allowHtml ? (
+                      <span dangerouslySetInnerHTML={{ __html: option.label }} />
+                    ) : (
+                      option.label
+                    )}
+                  </Label>
+                  {option.description && (
+                    <p className="text-muted-foreground text-xs">{option.description}</p>
+                  )}
+                </div>
+              </div>
+            )
+          })}
+        </div>
+        {component.searchable && query !== '' && visible.length === 0 && (
+          <p
+            data-slot="checkbox-list-empty"
+            role="status"
+            className="text-muted-foreground text-sm"
+          >
+            {component.noSearchResultsMessage ?? t('no_results', {}, 'No results.')}
+          </p>
+        )}
+      </div>
+    </FieldWrapper>
+  )
+}

package/src/components/fields/checkbox.tsx

@@ -0,0 +1,26 @@
+import type { CheckboxSchema } from '@alfakit/core'
+import { useField } from '../form/form-context'
+import { FieldWrapper } from '../schema/field-wrapper'
+import { Checkbox } from '../ui/checkbox'
+
+export function CheckboxField({ component }: { component: CheckboxSchema }) {
+  const { value, setValue, error, id, disabled, readOnly, aria } = useField<boolean | null>(
+    component,
+  )
+
+  return (
+    <FieldWrapper field={component} htmlFor={id} error={error} inline={component.inline}>
+      <Checkbox
+        id={id}
+        name={component.name}
+        checked={Boolean(value)}
+        onCheckedChange={(checked) => setValue(checked === true)}
+        disabled={disabled || readOnly}
+        aria-readonly={readOnly || undefined}
+        required={component.required}
+        {...aria}
+        className="mt-0.5"
+      />
+    </FieldWrapper>
+  )
+}

package/src/components/fields/code-editor-lazy.tsx

@@ -0,0 +1,33 @@
+import type { CodeEditorSchema } from '@alfakit/core'
+import { lazyComponent } from '../../lib/lazy'
+import { useField } from '../form/form-context'
+import { FieldWrapper } from '../schema/field-wrapper'
+
+/** What the server renders and hydration shows: the code, read-only and unhighlighted. */
+function CodeEditorPlaceholder({ component }: { component: CodeEditorSchema }) {
+  const { value, id, error } = useField<string | null>(component)
+
+  return (
+    <FieldWrapper field={component} htmlFor={id} error={error}>
+      <pre
+        dir="ltr"
+        data-slot="code-editor"
+        aria-busy="true"
+        className="border-input dark:bg-input/30 m-0 overflow-auto rounded-md border p-3 font-mono text-sm leading-6 whitespace-pre"
+        style={{
+          minHeight: component.minHeight ? `${component.minHeight}px` : undefined,
+          maxHeight: component.maxHeight ? `${component.maxHeight}px` : undefined,
+        }}
+      >
+        {typeof value === 'string' ? value : ''}
+        {'\n'}
+      </pre>
+    </FieldWrapper>
+  )
+}
+
+/** The code editor; its code loads the first time one is shown in the browser. */
+export const CodeEditorField = lazyComponent<{ component: CodeEditorSchema }>(
+  () => import('./code-editor').then((module) => module.CodeEditorField),
+  (props) => <CodeEditorPlaceholder {...props} />,
+)

package/src/components/fields/code-editor.tsx

@@ -0,0 +1,157 @@
+import type { CodeEditorSchema } from '@alfakit/core'
+import { countCodeLines, highlightCode, indentCode, newlineWithIndent } from '@alfakit/core'
+import { useMemo, useRef, type KeyboardEvent } from 'react'
+import { useT } from '../../context'
+import { extraProps } from '../../lib/attributes'
+import { cn } from '../../lib/utils'
+import { useField } from '../form/form-context'
+import { FieldWrapper } from '../schema/field-wrapper'
+import { codeTokenClasses } from './code-tokens'
+
+export { codeTokenClasses }
+
+/**
+ * A textarea layered over its highlighted copy: the browser keeps native editing,
+ * selection, undo and screen reader support, and the copy underneath shows the colours.
+ * Tab indents (Shift+Tab outdents); Escape then Tab moves focus on.
+ */
+export function CodeEditorField({ component }: { component: CodeEditorSchema }) {
+  const t = useT()
+  const { value, setValue, blur, error, id, disabled, readOnly, aria } = useField<string | null>(
+    component,
+  )
+  const code = typeof value === 'string' ? value : ''
+  const tokens = useMemo(() => highlightCode(code, component.language), [code, component.language])
+  const lines = countCodeLines(code)
+  const releaseTab = useRef(false)
+  const hintId = `${id}-tab-hint`
+  const locked = disabled || readOnly
+
+  const apply = (target: HTMLTextAreaElement, edit: ReturnType<typeof indentCode>) => {
+    setValue(edit.value)
+    // Restore the caret once React has written the new value.
+    requestAnimationFrame(() => target.setSelectionRange(edit.selectionStart, edit.selectionEnd))
+  }
+
+  const onKeyDown = (event: KeyboardEvent<HTMLTextAreaElement>) => {
+    if (locked) return
+
+    const target = event.currentTarget
+
+    if (event.key === 'Escape') {
+      releaseTab.current = true
+      return
+    }
+
+    if (event.key === 'Tab' && !releaseTab.current) {
+      event.preventDefault()
+      apply(
+        target,
+        indentCode(
+          code,
+          target.selectionStart,
+          target.selectionEnd,
+          component.tabSize,
+          event.shiftKey,
+        ),
+      )
+    } else if (event.key === 'Enter' && !event.shiftKey && !event.metaKey && !event.ctrlKey) {
+      event.preventDefault()
+      apply(target, newlineWithIndent(code, target.selectionStart, target.selectionEnd))
+    }
+
+    releaseTab.current = false
+  }
+
+  const wrap = Boolean(component.wrap)
+  const layer = cn(
+    'col-start-1 row-start-1 m-0 min-w-0 border-0 p-3 font-mono text-sm leading-6',
+    wrap ? 'break-words whitespace-pre-wrap' : 'whitespace-pre',
+  )
+
+  return (
+    <FieldWrapper field={component} htmlFor={id} error={error}>
+      <div
+        dir="ltr"
+        data-slot="code-editor"
+        data-language={component.language ?? undefined}
+        className={cn(
+          'border-input dark:bg-input/30 focus-within:border-ring focus-within:ring-ring/50 flex overflow-auto rounded-md border bg-transparent shadow-xs transition-[color,box-shadow] focus-within:ring-[3px]',
+          error && 'border-destructive',
+          disabled && 'opacity-50',
+        )}
+        style={{
+          minHeight: component.minHeight ? `${component.minHeight}px` : undefined,
+          maxHeight: component.maxHeight ? `${component.maxHeight}px` : undefined,
+        }}
+      >
+        {component.lineNumbers && (
+          <div
+            aria-hidden="true"
+            className="bg-muted/40 text-muted-foreground sticky start-0 shrink-0 border-e py-3 ps-3 pe-2 text-end font-mono text-sm leading-6 select-none"
+          >
+            {Array.from({ length: lines }, (_, index) => (
+              <div key={index}>{index + 1}</div>
+            ))}
+          </div>
+        )}
+        <div className="grid min-w-0 flex-1">
+          <pre aria-hidden="true" className={cn(layer, 'pointer-events-none')}>
+            {tokens.map((token, index) =>
+              token.kind === 'plain' ? (
+                token.text
+              ) : (
+                <span key={index} className={codeTokenClasses[token.kind]}>
+                  {token.text}
+                </span>
+              ),
+            )}
+            {/* Keeps a trailing newline's empty line visible. */}
+            {'\n'}
+          </pre>
+          <textarea
+            id={id}
+            name={component.name}
+            value={code}
+            onChange={(event) => setValue(event.target.value)}
+            onKeyDown={onKeyDown}
+            onBlur={blur}
+            disabled={disabled}
+            readOnly={readOnly}
+            required={component.required}
+            autoFocus={component.autofocus}
+            maxLength={component.maxLength}
+            placeholder={component.placeholder}
+            spellCheck={false}
+            autoCapitalize="off"
+            autoComplete="off"
+            autoCorrect="off"
+            wrap={wrap ? 'soft' : 'off'}
+            {...aria}
+            aria-describedby={
+              [aria['aria-describedby'], locked ? null : hintId].filter(Boolean).join(' ') ||
+              undefined
+            }
+            {...extraProps(
+              component.extraInputAttributes,
+              cn(
+                layer,
+                'caret-foreground placeholder:text-muted-foreground selection:bg-primary/25 resize-none overflow-hidden bg-transparent text-transparent outline-none selection:text-transparent',
+              ),
+            )}
+            style={{ tabSize: component.tabSize }}
+          />
+        </div>
+      </div>
+      {!locked && (
+        <span id={hintId} className="sr-only">
+          {t(
+            'code_editor.tab_hint',
+            {},
+            'Tab indents. Press Escape, then Tab, to leave the editor.',
+          )}
+        </span>
+      )}
+    </FieldWrapper>
+  )
+}

package/src/components/fields/code-tokens.ts

@@ -0,0 +1,15 @@
+import type { CodeTokenKind } from '@alfakit/core'
+
+/** Token colours; spelled out so Tailwind keeps them. */
+export const codeTokenClasses: Record<CodeTokenKind, string> = {
+  plain: '',
+  comment: 'text-muted-foreground italic',
+  string: 'text-emerald-700 dark:text-emerald-400',
+  number: 'text-amber-700 dark:text-amber-400',
+  keyword: 'text-violet-700 dark:text-violet-400',
+  literal: 'text-orange-700 dark:text-orange-400',
+  tag: 'text-sky-700 dark:text-sky-400',
+  attribute: 'text-amber-800 dark:text-amber-300',
+  property: 'text-sky-800 dark:text-sky-300',
+  variable: 'text-rose-700 dark:text-rose-400',
+}

package/src/components/fields/color-picker.tsx

@@ -0,0 +1,72 @@
+import type { ColorPickerSchema } from '@alfakit/core'
+import { colorAlpha, colorToHex, formatColor, withColorAlpha } from '@alfakit/core'
+import { useFormatter, useT } from '../../context'
+import { extraProps } from '../../lib/attributes'
+import { useField } from '../form/form-context'
+import { FieldWrapper } from '../schema/field-wrapper'
+import { Input } from '../ui/input'
+
+export function ColorPickerField({ component }: { component: ColorPickerSchema }) {
+  const t = useT()
+  const format = useFormatter()
+  const { value, setValue, blur, error, id, disabled, readOnly, aria } = useField<string | null>(
+    component,
+  )
+  const isHex = component.format === 'hex'
+  // `rgba()`: the native swatch has no alpha, so a slider sets the opacity.
+  const alpha = Math.round(colorAlpha(value) * 100)
+
+  return (
+    <FieldWrapper field={component} htmlFor={id} error={error}>
+      <div className="flex items-center gap-2">
+        <label
+          className="border-input relative size-9 shrink-0 cursor-pointer overflow-hidden rounded-md border shadow-xs"
+          style={{ backgroundColor: value ?? 'transparent' }}
+          aria-label={t('form.pick_color', {}, 'Pick a colour')}
+        >
+          <input
+            type="color"
+            value={colorToHex(value) ?? '#000000'}
+            onChange={(event) => setValue(formatColor(event.target.value, component.format, value))}
+            onBlur={blur}
+            disabled={disabled || readOnly}
+            className="absolute inset-0 size-full cursor-pointer opacity-0"
+          />
+        </label>
+        <Input
+          id={id}
+          name={component.name}
+          value={value ?? ''}
+          onChange={(event) => setValue(event.target.value)}
+          onBlur={blur}
+          placeholder={component.placeholder ?? (isHex ? '#000000' : component.format)}
+          disabled={disabled}
+          readOnly={readOnly}
+          {...aria}
+
+          {...extraProps(component.extraInputAttributes, 'font-mono')}
+        />
+      </div>
+      {component.format === 'rgba' && (
+        <div data-slot="color-picker-alpha" className="mt-2 flex items-center gap-2">
+          <input
+            type="range"
+            min={0}
+            max={100}
+            step={1}
+            value={alpha}
+            onChange={(event) => setValue(withColorAlpha(value, Number(event.target.value) / 100))}
+            onBlur={blur}
+            disabled={disabled || readOnly}
+            aria-label={t('form.color_opacity', {}, 'Opacity')}
+            aria-valuetext={`${alpha}%`}
+            className="accent-primary h-2 flex-1 cursor-pointer disabled:cursor-not-allowed disabled:opacity-50"
+          />
+          <span className="text-muted-foreground w-10 text-end text-xs tabular-nums">
+            {format.percent(alpha / 100)}
+          </span>
+        </div>
+      )}
+    </FieldWrapper>
+  )
+}