@alfakit/vue 0.0.0-stage → 0.1.1

package/src/components/schema/ContentSlot.vue

@@ -0,0 +1,79 @@
+<script setup lang="ts">
+import type {
+  AnyActionSchema,
+  ContentSlotName,
+  ContentSlots,
+  FieldActions,
+  SchemaComponent,
+} from '@alfakit/core'
+import { slotAlignmentClass } from '@alfakit/core'
+import { computed, type HTMLAttributes } from 'vue'
+import { cn } from '../../lib/utils'
+import ActionList from '../actions/ActionList.vue'
+import { useFieldActionContext } from './field-actions'
+import RenderComponent from './RenderComponent.vue'
+
+/**
+ * One content slot of a field or entry (`aboveLabel()`, `belowContent()`…): a small row
+ * of schema components and actions. Actions run as the owner's field actions.
+ */
+const props = defineProps<{
+  component: ContentSlots & FieldActions & { key: string }
+  name: ContentSlotName
+  class?: HTMLAttributes['class']
+}>()
+
+const context = useFieldActionContext(() => props.component)
+const slot = computed(() => props.component.slots?.[props.name])
+
+type Group =
+  | { kind: 'actions'; key: string; actions: AnyActionSchema[] }
+  | { kind: 'component'; key: string; component: SchemaComponent }
+
+// Consecutive actions share one action list, so they sit together like hint actions.
+const groups = computed<Group[]>(() => {
+  const result: Group[] = []
+
+  for (const item of slot.value?.items ?? []) {
+    if (item.action) {
+      const last = result[result.length - 1]
+
+      if (last?.kind === 'actions') {
+        last.actions.push(item.action)
+      } else {
+        result.push({ kind: 'actions', key: `actions-${result.length}`, actions: [item.action] })
+      }
+    } else {
+      result.push({ kind: 'component', key: item.component.key, component: item.component })
+    }
+  }
+
+  return result
+})
+</script>
+
+<template>
+  <div
+    v-if="slot?.items.length"
+    data-slot="field-content-slot"
+    :data-content-slot="props.name"
+    :class="
+      cn(
+        'flex min-w-0 flex-wrap items-center gap-2 text-sm',
+        slotAlignmentClass(slot.alignment),
+        props.class,
+      )
+    "
+  >
+    <template v-for="group in groups" :key="group.key">
+      <ActionList
+        v-if="group.kind === 'actions'"
+        :actions="group.actions"
+        :context="context"
+        size="xs"
+        class="gap-1"
+      />
+      <RenderComponent v-else :component="group.component" />
+    </template>
+  </div>
+</template>

package/src/components/schema/FieldAffixActions.vue

@@ -0,0 +1,35 @@
+<script setup lang="ts">
+import type { FieldActions } from '@alfakit/core'
+import { computed } from 'vue'
+import ActionList from '../actions/ActionList.vue'
+import { useFieldActionContext } from './field-actions'
+
+/** Prefix and suffix actions of a field or entry, on either side of the control. */
+const props = defineProps<{ component: FieldActions & { key: string } }>()
+const context = useFieldActionContext(() => props.component)
+const prefix = computed(() => props.component.prefixActions ?? [])
+const suffix = computed(() => props.component.suffixActions ?? [])
+</script>
+
+<template>
+  <div
+    v-if="prefix.length > 0 || suffix.length > 0"
+    data-slot="field-affix-actions"
+    class="flex items-start gap-2"
+  >
+    <ActionList
+      v-if="prefix.length > 0"
+      :actions="prefix"
+      :context="context"
+      class="shrink-0 flex-nowrap gap-1"
+    />
+    <div class="min-w-0 flex-1"><slot /></div>
+    <ActionList
+      v-if="suffix.length > 0"
+      :actions="suffix"
+      :context="context"
+      class="shrink-0 flex-nowrap gap-1"
+    />
+  </div>
+  <slot v-else />
+</template>

package/src/components/schema/FieldHintActions.vue

@@ -0,0 +1,19 @@
+<script setup lang="ts">
+import type { FieldActions } from '@alfakit/core'
+import ActionList from '../actions/ActionList.vue'
+import { useFieldActionContext } from './field-actions'
+
+/** Hint actions of a field or entry, next to its label. */
+const props = defineProps<{ component: FieldActions & { key: string } }>()
+const context = useFieldActionContext(() => props.component)
+</script>
+
+<template>
+  <ActionList
+    v-if="props.component.hintActions?.length"
+    :actions="props.component.hintActions"
+    :context="context"
+    size="xs"
+    class="gap-1"
+  />
+</template>

package/src/components/schema/FieldWrapper.vue

@@ -0,0 +1,276 @@
+<script setup lang="ts">
+import type { BaseField } from '@alfakit/core'
+import { fieldIds, hasSlots, mergeAttributes } from '@alfakit/core'
+import { computed, type HTMLAttributes } from 'vue'
+import { textColorClasses } from '../../lib/colors'
+import { Icon } from '../../lib/icons'
+import { cn } from '../../lib/utils'
+import Label from '../ui/Label.vue'
+import ContentSlot from './ContentSlot.vue'
+import FieldAffixActions from './FieldAffixActions.vue'
+import FieldHintActions from './FieldHintActions.vue'
+import { useInFusedGroup } from './fused-group'
+
+/**
+ * Label, hint, content slots, helper text and validation error around a form control.
+ */
+const props = withDefaults(
+  defineProps<{
+    field: BaseField
+    htmlFor: string
+    error?: string
+    /** Render the label after the control (checkbox, toggle). */
+    inline?: boolean
+    class?: HTMLAttributes['class']
+    /** Suppress the label (the control renders its own). */
+    hideLabel?: boolean
+  }>(),
+  { inline: false, hideLabel: false },
+)
+
+const fused = useInFusedGroup()
+const label = computed(() => (props.hideLabel ? null : props.field.label))
+// Stable ids the control references through `aria-describedby` / `aria-labelledby`.
+const ids = computed(() => fieldIds(props.htmlFor))
+const hintUrl = computed(() =>
+  typeof props.field.meta?.hintUrl === 'string' ? props.field.meta.hintUrl : undefined,
+)
+const wrapperAttributes = computed(() =>
+  mergeAttributes(props.field.extraAttributes, props.field.extraFieldWrapperAttributes),
+)
+// `afterLabel()` sits with the hint at the end of the label row unless aligned to the start.
+const afterLabelAtStart = computed(() => props.field.slots?.afterLabel?.alignment === 'start')
+const hasLabelLine = computed(
+  () =>
+    Boolean(label.value) ||
+    Boolean(props.field.slots?.beforeLabel) ||
+    (Boolean(props.field.slots?.afterLabel) && afterLabelAtStart.value),
+)
+const hasHint = computed(
+  () =>
+    Boolean(props.field.hint) ||
+    Boolean(props.field.hintActions?.length) ||
+    (Boolean(props.field.slots?.afterLabel) && !afterLabelAtStart.value),
+)
+const hasSideSlots = computed(() => hasSlots(props.field, ['beforeContent', 'afterContent']))
+const hintClass = computed(() =>
+  cn(
+    'inline-flex items-center gap-1 text-xs',
+    props.field.hintColor ? textColorClasses[props.field.hintColor] : 'text-muted-foreground',
+  ),
+)
+</script>
+
+<template>
+  <!-- Inside a FusedGroup: the control only; the label stays for screen readers and the
+       group shows the error. -->
+  <div
+    v-if="fused"
+    data-slot="field"
+    :data-field="props.field.statePath"
+    data-fused=""
+    :class="cn('flex h-full flex-col', props.class)"
+    v-bind="wrapperAttributes"
+  >
+    <Label v-if="label" :id="ids.label" :for="props.htmlFor" class="sr-only">{{ label }}</Label>
+    <FieldAffixActions :component="props.field"><slot /></FieldAffixActions>
+    <p
+      v-if="props.error && props.field.allowHtmlValidationMessages"
+      :id="ids.error"
+      class="sr-only"
+      role="alert"
+      v-html="props.error"
+    />
+    <p v-else-if="props.error" :id="ids.error" class="sr-only" role="alert">
+      {{ props.error }}
+    </p>
+  </div>
+  <div
+    v-else
+    data-slot="field"
+    :data-field="props.field.statePath"
+    :data-inline-label="props.field.inlineLabel ? '' : undefined"
+    :class="
+      cn(
+        'flex flex-col gap-1.5',
+        props.field.inlineLabel && 'sm:grid sm:grid-cols-3 sm:items-start sm:gap-x-4',
+        props.class,
+      )
+    "
+    v-bind="wrapperAttributes"
+  >
+    <template v-if="!props.field.inlineLabel">
+      <ContentSlot
+        v-if="props.field.slots?.aboveLabel"
+        :component="props.field"
+        name="aboveLabel"
+      />
+    </template>
+    <!-- `inlineLabel()`: label in the first column, the control in the other two from sm up;
+         stacked on phones. Grid columns follow the text direction, so RTL works. -->
+    <div
+      v-if="props.field.inlineLabel || (!props.inline && (hasLabelLine || hasHint))"
+      :data-slot="props.field.inlineLabel ? 'field-label' : undefined"
+      :class="
+        props.field.inlineLabel
+          ? 'flex flex-col gap-1 sm:pt-2'
+          : 'flex items-center justify-between gap-2'
+      "
+    >
+      <ContentSlot
+        v-if="props.field.slots?.aboveLabel && props.field.inlineLabel"
+        :component="props.field"
+        name="aboveLabel"
+      />
+      <span v-if="hasLabelLine" class="inline-flex min-w-0 items-center gap-2">
+        <ContentSlot
+          v-if="props.field.slots?.beforeLabel"
+          :component="props.field"
+          name="beforeLabel"
+        />
+        <Label v-if="label" :id="ids.label" :for="props.htmlFor">
+          <span>
+            {{ label
+            }}<span v-if="props.field.required" class="text-destructive ms-0.5" aria-hidden="true"
+              >*</span
+            >
+          </span>
+        </Label>
+        <ContentSlot
+          v-if="props.field.slots?.afterLabel && afterLabelAtStart"
+          :component="props.field"
+          name="afterLabel"
+        />
+      </span>
+      <span v-else-if="!props.field.inlineLabel" />
+      <span v-if="hasHint" class="inline-flex items-center gap-2">
+        <span v-if="props.field.hint" :id="ids.hint" :class="hintClass">
+          <Icon v-if="props.field.hintIcon" :name="props.field.hintIcon" class="size-3.5" />
+          <a v-if="hintUrl" :href="hintUrl" class="hover:underline" v-html="props.field.hint" />
+          <span v-else v-html="props.field.hint" />
+        </span>
+        <FieldHintActions v-if="props.field.hintActions?.length" :component="props.field" />
+        <ContentSlot
+          v-if="props.field.slots?.afterLabel && !afterLabelAtStart"
+          :component="props.field"
+          name="afterLabel"
+        />
+      </span>
+      <ContentSlot
+        v-if="props.field.slots?.belowLabel && props.field.inlineLabel"
+        :component="props.field"
+        name="belowLabel"
+      />
+    </div>
+    <div v-if="props.inline && !props.field.inlineLabel" class="flex items-start gap-2">
+      <FieldAffixActions :component="props.field"><slot /></FieldAffixActions>
+      <div class="flex flex-col gap-1">
+        <span v-if="hasLabelLine" class="inline-flex min-w-0 items-center gap-2">
+          <ContentSlot
+            v-if="props.field.slots?.beforeLabel"
+            :component="props.field"
+            name="beforeLabel"
+          />
+          <Label
+            v-if="label"
+            :id="ids.label"
+            :for="props.htmlFor"
+            class="cursor-pointer font-normal"
+          >
+            <span>
+              {{ label
+              }}<span v-if="props.field.required" class="text-destructive ms-0.5" aria-hidden="true"
+                >*</span
+              >
+            </span>
+          </Label>
+          <ContentSlot
+            v-if="props.field.slots?.afterLabel && afterLabelAtStart"
+            :component="props.field"
+            name="afterLabel"
+          />
+        </span>
+        <span v-if="hasHint" class="inline-flex items-center gap-2">
+          <span v-if="props.field.hint" :id="ids.hint" :class="hintClass">
+            <Icon v-if="props.field.hintIcon" :name="props.field.hintIcon" class="size-3.5" />
+            <a v-if="hintUrl" :href="hintUrl" class="hover:underline" v-html="props.field.hint" />
+            <span v-else v-html="props.field.hint" />
+          </span>
+          <FieldHintActions v-if="props.field.hintActions?.length" :component="props.field" />
+          <ContentSlot
+            v-if="props.field.slots?.afterLabel && !afterLabelAtStart"
+            :component="props.field"
+            name="afterLabel"
+          />
+        </span>
+      </div>
+    </div>
+    <div
+      :class="props.field.inlineLabel ? 'flex min-w-0 flex-col gap-1.5 sm:col-span-2' : 'contents'"
+    >
+      <ContentSlot
+        v-if="props.field.slots?.belowLabel && !props.field.inlineLabel"
+        :component="props.field"
+        name="belowLabel"
+      />
+      <template v-if="!props.inline || props.field.inlineLabel">
+        <ContentSlot
+          v-if="props.field.slots?.aboveContent"
+          :component="props.field"
+          name="aboveContent"
+        />
+        <div v-if="hasSideSlots" data-slot="field-content" class="flex items-center gap-2">
+          <ContentSlot
+            v-if="props.field.slots?.beforeContent"
+            :component="props.field"
+            name="beforeContent"
+            class="shrink-0 flex-nowrap"
+          />
+          <div class="min-w-0 flex-1">
+            <FieldAffixActions :component="props.field"><slot /></FieldAffixActions>
+          </div>
+          <ContentSlot
+            v-if="props.field.slots?.afterContent"
+            :component="props.field"
+            name="afterContent"
+            class="shrink-0 flex-nowrap"
+          />
+        </div>
+        <FieldAffixActions v-else :component="props.field"><slot /></FieldAffixActions>
+      </template>
+      <p
+        v-if="props.field.helperText"
+        :id="ids.helper"
+        class="text-muted-foreground text-xs"
+        v-html="props.field.helperText"
+      />
+      <ContentSlot
+        v-if="props.field.slots?.belowContent"
+        :component="props.field"
+        name="belowContent"
+      />
+      <template v-if="props.error">
+        <ContentSlot
+          v-if="props.field.slots?.aboveErrorMessage"
+          :component="props.field"
+          name="aboveErrorMessage"
+        />
+        <p
+          v-if="props.field.allowHtmlValidationMessages"
+          :id="ids.error"
+          class="text-destructive text-xs"
+          role="alert"
+          v-html="props.error"
+        />
+        <p v-else :id="ids.error" class="text-destructive text-xs" role="alert">
+          {{ props.error }}
+        </p>
+        <ContentSlot
+          v-if="props.field.slots?.belowErrorMessage"
+          :component="props.field"
+          name="belowErrorMessage"
+        />
+      </template>
+    </div>
+  </div>
+</template>

package/src/components/schema/RenderComponent.vue

@@ -0,0 +1,69 @@
+<script setup lang="ts">
+import type { BaseField, SchemaComponent } from '@alfakit/core'
+import {
+  columnOrderClasses,
+  columnSpanClasses,
+  columnStartClasses,
+  containerColumnSpanClasses,
+} from '@alfakit/core'
+import { computed } from 'vue'
+import { useRegistry } from '../../context'
+import { cn } from '../../lib/utils'
+import TranslatableField from './TranslatableField.vue'
+
+const props = defineProps<{ component: SchemaComponent }>()
+const registry = useRegistry()
+
+const type = computed(() =>
+  props.component.type === 'View'
+    ? ((props.component as { component?: string }).component ?? 'View')
+    : props.component.type,
+)
+const resolved = computed(
+  () =>
+    registry.resolve(type.value) ??
+    (props.component.type === 'View' ? registry.resolve('View') : undefined),
+)
+const translatable = computed(() =>
+  Boolean((props.component as Partial<BaseField>).translatable?.locales?.length),
+)
+const span = computed(() =>
+  cn(
+    columnSpanClasses(props.component.columnSpan),
+    containerColumnSpanClasses(props.component.columnSpan),
+    columnStartClasses(props.component.columnStart),
+    columnOrderClasses(props.component.columnOrder),
+  ),
+)
+// Registered `View` components get the PHP `props` spread, as the docs describe.
+const viewProps = computed(() =>
+  props.component.type === 'View'
+    ? ((props.component as { props?: Record<string, unknown> }).props ?? {})
+    : {},
+)
+</script>
+
+<template>
+  <div
+    v-if="!resolved"
+    :class="
+      cn('border-destructive/40 text-destructive rounded-md border border-dashed p-3 text-xs', span)
+    "
+  >
+    Unknown component type <code class="font-mono">{{ type }}</code
+    >. Register it with <code class="font-mono">createAlfakit({ components })</code>.
+  </div>
+  <div
+    v-else
+    data-slot="schema-item"
+    :data-type="props.component.type"
+    :class="cn('min-w-0', span || undefined)"
+  >
+    <TranslatableField
+      v-if="translatable"
+      :component="props.component as BaseField"
+      :render="resolved"
+    />
+    <component :is="resolved" v-else v-bind="viewProps" :component="props.component" />
+  </div>
+</template>

package/src/components/schema/SchemaRenderer.vue

@@ -0,0 +1,63 @@
+<script setup lang="ts">
+import type { Attributes, Breakpoints, SchemaComponent } from '@alfakit/core'
+import {
+  containerGridColumnsClasses,
+  gridColumnsClasses,
+  hasContainerBreakpoints,
+} from '@alfakit/core'
+import type { HTMLAttributes } from 'vue'
+import { cn } from '../../lib/utils'
+import RenderComponent from './RenderComponent.vue'
+
+/**
+ * Renders a list of schema components in a responsive grid, resolving each component's
+ * `type` through the registry.
+ */
+const props = defineProps<{
+  components: SchemaComponent[]
+  columns?: Breakpoints
+  class?: HTMLAttributes['class']
+  /** `extraAttributes` of the layout component that owns this grid (Grid, Group, Tab, Step). */
+  attributes?: Attributes
+}>()
+</script>
+
+<template>
+  <!-- `@md`-style columns follow the width of this wrapper instead of the viewport. -->
+  <div
+    v-if="hasContainerBreakpoints(props.columns)"
+    data-slot="schema-container"
+    class="@container"
+  >
+    <div
+      v-bind="props.attributes ?? {}"
+      data-slot="schema"
+      :class="
+        cn(
+          'grid gap-6',
+          gridColumnsClasses(props.columns ?? { default: 1 }),
+          containerGridColumnsClasses(props.columns),
+          props.class,
+        )
+      "
+    >
+      <RenderComponent
+        v-for="component in props.components"
+        :key="component.key"
+        :component="component"
+      />
+    </div>
+  </div>
+  <div
+    v-else
+    v-bind="props.attributes ?? {}"
+    data-slot="schema"
+    :class="cn('grid gap-6', gridColumnsClasses(props.columns ?? { default: 1 }), props.class)"
+  >
+    <RenderComponent
+      v-for="component in props.components"
+      :key="component.key"
+      :component="component"
+    />
+  </div>
+</template>

package/src/components/schema/TranslatableField.vue

@@ -0,0 +1,95 @@
+<script setup lang="ts">
+import type { BaseField } from '@alfakit/core'
+import {
+  initialTranslatableLocale,
+  translatableLocaleField,
+  translatableLocalesWithErrors,
+} from '@alfakit/core'
+import { computed, ref, watch, type Component } from 'vue'
+import { useStoreSelector } from '../../composables/use-store'
+import { useT } from '../../context'
+import { cn } from '../../lib/utils'
+import { useFormStore } from '../form/form-context'
+
+/**
+ * A `->translatable()` field: a language switcher above the field's own renderer, bound
+ * to `{statePath}.{locale}` for the selected language. Languages with a validation error
+ * are marked, and the first of them opens after a failed submit.
+ */
+const props = defineProps<{ component: BaseField; render: Component }>()
+const t = useT()
+const store = useFormStore()
+
+const locales = computed(() => props.component.translatable?.locales ?? [])
+const invalidKey = useStoreSelector(store.store, (state) =>
+  translatableLocalesWithErrors(props.component, state.errors).join(','),
+)
+const invalid = computed(() => (invalidKey.value === '' ? [] : invalidKey.value.split(',')))
+const current = ref(initialTranslatableLocale(props.component, store.store.get().errors))
+
+// After a failed submit, show a language that needs attention.
+watch(invalidKey, () => {
+  if (invalid.value.length > 0 && !invalid.value.includes(current.value)) {
+    current.value = invalid.value[0]!
+  }
+})
+
+// A `LocaleSwitcher` changes the language the fields open on; follow it when it changes.
+watch(
+  () => props.component.translatable?.defaultLocale ?? '',
+  (editing) => {
+    if (editing !== '' && locales.value.some((option) => option.code === editing)) {
+      current.value = editing
+    }
+  },
+)
+
+const locale = computed(
+  () => locales.value.find((candidate) => candidate.code === current.value) ?? locales.value[0],
+)
+const field = computed(() =>
+  locale.value ? translatableLocaleField(props.component, locale.value) : props.component,
+)
+</script>
+
+<template>
+  <div v-if="locale" data-slot="translatable-field" class="flex flex-col gap-1.5">
+    <div
+      role="group"
+      :aria-label="
+        t('translatable.languages', { field: props.component.label ?? props.component.name })
+      "
+      data-slot="translatable-locales"
+      class="flex flex-wrap justify-end gap-1"
+    >
+      <button
+        v-for="option in locales"
+        :key="option.code"
+        type="button"
+        :lang="option.tag"
+        :aria-pressed="option.code === locale.code"
+        :data-active="option.code === locale.code || undefined"
+        :data-invalid="invalid.includes(option.code) || undefined"
+        :class="
+          cn(
+            'focus-visible:ring-ring/50 inline-flex h-6 items-center gap-1 rounded-md border px-2 text-xs font-medium transition-colors outline-none focus-visible:ring-[3px]',
+            option.code === locale.code
+              ? 'border-primary bg-primary text-primary-foreground'
+              : 'bg-background text-muted-foreground hover:bg-accent hover:text-accent-foreground',
+            invalid.includes(option.code) &&
+              option.code !== locale.code &&
+              'border-destructive text-destructive',
+          )
+        "
+        @click="current = option.code"
+      >
+        {{ option.label }}
+        <template v-if="invalid.includes(option.code)">
+          <span aria-hidden="true" class="bg-destructive size-1.5 rounded-full" />
+          <span class="sr-only">({{ t('translatable.has_errors') }})</span>
+        </template>
+      </button>
+    </div>
+    <component :is="props.render" :key="locale.code" :component="field" />
+  </div>
+</template>

package/src/components/schema/VirtualSpacerRow.vue

@@ -0,0 +1,19 @@
+<script setup lang="ts">
+/**
+ * Reserves the height of table rows outside the rendered window, so the scrollbar and the
+ * positions of the rendered rows stay right. Hidden from assistive technology: the
+ * `aria-rowcount` on the table tells the real count.
+ */
+defineProps<{ height: number; colSpan: number }>()
+</script>
+
+<template>
+  <tr
+    v-if="height > 0"
+    aria-hidden="true"
+    data-slot="virtual-spacer"
+    :style="{ height: `${height}px` }"
+  >
+    <td :colspan="colSpan" class="border-0 p-0" />
+  </tr>
+</template>

package/src/components/schema/field-actions.ts

@@ -0,0 +1,21 @@
+import type { ActionContext } from '@alfakit/core'
+import { fieldActionContext } from '@alfakit/core'
+import { computed, toValue, type ComputedRef, type MaybeRefOrGetter } from 'vue'
+import { usePageActionContext } from '../actions/action-context'
+import { useOptionalFormStore } from '../form/form-context'
+
+/**
+ * The action context of a field or entry's own actions (`field:{schema}::{key}`): they
+ * run through the action endpoint with the form's state, and the response updates the
+ * form in place.
+ */
+export function useFieldActionContext(
+  component: MaybeRefOrGetter<{ key: string }>,
+): ComputedRef<ActionContext> {
+  const form = useOptionalFormStore()
+  const page = usePageActionContext()
+
+  return computed(() =>
+    fieldActionContext({ token: page.token, form, key: toValue(component).key }),
+  )
+}