@octabits-io/nuxt-ui-kit 0.2.0 → 0.3.0

package/src/components/PageAction.vue

@@ -0,0 +1,88 @@
+<script setup lang="ts">
+// Shipped as source: the consumer's Vite compiles this SFC. All imports are
+// explicit — no reliance on the consumer's auto-import configuration.
+import { computed, useSlots } from 'vue'
+import type { RouteLocationRaw } from 'vue-router'
+import UTooltip from '@nuxt/ui/components/Tooltip.vue'
+import UButton from '@nuxt/ui/components/Button.vue'
+import type { ButtonProps } from '@nuxt/ui'
+
+type Tone = 'primary' | 'neutral' | 'destructive'
+
+/**
+ * Normalized page-header action button: icon-only renders with a tooltip and
+ * aria-label from the required `label`; a default slot or `showLabel` renders
+ * the label text inline. `destructive` is only valid inside `PageActionMenu`.
+ */
+const props = withDefaults(defineProps<{
+  /** Icon name (required). */
+  icon: string
+  /** Required. Used as tooltip text for icon-only buttons and aria-label otherwise. */
+  label: string
+  /** Visual tone. `destructive` is only valid inside PageActionMenu. */
+  tone?: Tone
+  loading?: boolean
+  disabled?: boolean
+  to?: RouteLocationRaw
+  /** Link target, e.g. '_blank' for external links (only meaningful with `to`). */
+  target?: string
+  /** Force the button to render label text. If absent, a default slot determines it. */
+  showLabel?: boolean
+  /** Whether the tooltip should respect global disabled state. */
+  tooltipDisabled?: boolean
+}>(), {
+  tone: 'neutral',
+  loading: false,
+  disabled: false,
+  showLabel: false,
+  tooltipDisabled: false,
+})
+
+const slots = useSlots()
+
+const hasLabelSlot = computed(() => Boolean(slots.default))
+const isIconOnly = computed(() => !hasLabelSlot.value && !props.showLabel)
+
+const buttonProps = computed<Partial<ButtonProps>>(() => {
+  const base: Partial<ButtonProps> = {
+    icon: props.icon,
+    size: 'sm',
+    loading: props.loading,
+    disabled: props.disabled || props.loading,
+    to: props.to,
+    target: props.target,
+  }
+  switch (props.tone) {
+    case 'primary':
+      return { ...base, color: 'primary', variant: 'solid' }
+    case 'destructive':
+      if (import.meta.dev) {
+        console.warn('[PageAction] tone="destructive" should be used inside PageActionMenu, not inline.')
+      }
+      return { ...base, color: 'error', variant: 'ghost' }
+    case 'neutral':
+    default:
+      return { ...base, color: 'neutral', variant: 'ghost' }
+  }
+})
+
+if (import.meta.dev && !props.label) {
+  console.warn('[PageAction] `label` is required (used as tooltip text for icon-only buttons).')
+}
+</script>
+
+<template>
+  <UTooltip v-if="isIconOnly" :text="label" :disabled="tooltipDisabled">
+    <UButton
+      v-bind="buttonProps"
+      :aria-label="label"
+    />
+  </UTooltip>
+  <UButton
+    v-else
+    v-bind="buttonProps"
+    :label="showLabel ? label : undefined"
+  >
+    <slot />
+  </UButton>
+</template>

package/src/components/PageActionMenu.vue

@@ -0,0 +1,34 @@
+<script setup lang="ts">
+// Shipped as source: the consumer's Vite compiles this SFC. All imports are
+// explicit — no reliance on the consumer's auto-import configuration.
+// i18n key contract: pageChrome.moreActions.
+import { useI18n } from 'vue-i18n'
+import UDropdownMenu from '@nuxt/ui/components/DropdownMenu.vue'
+import type { DropdownMenuItem } from '@nuxt/ui'
+import PageAction from './PageAction.vue'
+
+/**
+ * Overflow/dropdown menu trigger that matches PageAction sizing. Accepts the
+ * grouped `DropdownMenuItem[][]` shape. Destructive actions should set
+ * `color: 'error'` on the item.
+ */
+withDefaults(defineProps<{
+  items: DropdownMenuItem[][]
+  icon?: string
+  label?: string
+}>(), {
+  icon: 'i-lucide-ellipsis-vertical',
+  label: undefined,
+})
+
+const { t } = useI18n()
+</script>
+
+<template>
+  <UDropdownMenu v-if="items.length" :items="items">
+    <PageAction
+      :icon="icon"
+      :label="label ?? t('pageChrome.moreActions')"
+    />
+  </UDropdownMenu>
+</template>

package/src/components/PageHeader.vue

@@ -0,0 +1,110 @@
+<script setup lang="ts">
+// Shipped as source: the consumer's Vite compiles this SFC. All imports are
+// explicit — no reliance on the consumer's auto-import configuration.
+// i18n key contract: pageChrome.back (+ PageActionMenu/PageUtilityActions keys).
+import { computed } from 'vue'
+import { useI18n } from 'vue-i18n'
+import { useRouter, type RouteLocationRaw } from 'vue-router'
+import UButton from '@nuxt/ui/components/Button.vue'
+import USkeleton from '@nuxt/ui/components/Skeleton.vue'
+import type { DropdownMenuItem } from '@nuxt/ui'
+import PageActionMenu from './PageActionMenu.vue'
+import PageUtilityActions from './PageUtilityActions.vue'
+
+/**
+ * Standard page header.
+ *
+ * Conventions enforced by this component and its siblings:
+ * - Max 3 neutral icon buttons inline in `#actions`; more go in `overflowItems`.
+ * - Destructive actions are ALWAYS placed inside the overflow menu, never inline.
+ * - Header height, spacing, and tooltip behavior are normalized via `PageAction`.
+ * - Utility triggers (Help, AI history, …) live in `#utility` (default =
+ *   `PageUtilityActions`) and render as LABELED buttons, not icon-only.
+ */
+const props = withDefaults(defineProps<{
+  title?: string
+  subtitle?: string
+  /** Show a leading back button. `true` uses router.back(); pass `{ to }` to navigate. */
+  back?: boolean | { to: RouteLocationRaw }
+  /** Show skeleton title while loading. */
+  loading?: boolean
+  /**
+   * `default` = full-width top-of-page header with padding.
+   * `compact` = sits inside a detail panel / sidebar; smaller title + thinner divider.
+   * `flush`   = no padding/border (caller wraps it).
+   */
+  density?: 'default' | 'compact' | 'flush'
+  /** When false, the default utility cluster is hidden. */
+  utility?: boolean
+  /** Optional grouped overflow items. Alternative to using the #overflow slot. */
+  overflowItems?: DropdownMenuItem[][]
+}>(), {
+  back: false,
+  loading: false,
+  density: 'default',
+  utility: true,
+  overflowItems: () => [],
+})
+
+const { t } = useI18n()
+const router = useRouter()
+
+function onBack() {
+  if (typeof props.back === 'object' && props.back && 'to' in props.back) {
+    router.push(props.back.to)
+    return
+  }
+  router.back()
+}
+
+const wrapperClass = computed(() => {
+  switch (props.density) {
+    case 'compact':
+      return 'flex items-center gap-2 flex-wrap border-b border-default px-6 py-4'
+    case 'flush':
+      return 'flex items-center gap-2 flex-wrap'
+    case 'default':
+    default:
+      return 'flex items-center gap-2 flex-wrap'
+  }
+})
+
+const titleClass = computed(() => props.density === 'compact' ? 'font-display text-lg font-semibold tracking-tight' : 'font-display text-2xl font-semibold tracking-tight')
+</script>
+
+<template>
+  <div :class="wrapperClass">
+    <UButton
+      v-if="back"
+      icon="i-lucide-arrow-left"
+      color="neutral"
+      variant="ghost"
+      size="sm"
+      :aria-label="t('pageChrome.back')"
+      @click="onBack"
+    />
+
+    <div class="min-w-0">
+      <slot name="title">
+        <USkeleton v-if="loading" class="h-7 w-40" />
+        <h1 v-else-if="title" :class="titleClass">{{ title }}</h1>
+      </slot>
+      <p v-if="subtitle && !loading" class="text-sm text-muted mt-1">{{ subtitle }}</p>
+    </div>
+
+    <div v-if="$slots.badges" class="flex items-center gap-2">
+      <slot name="badges" />
+    </div>
+
+    <div class="ml-auto flex items-center gap-1">
+      <slot name="actions" />
+      <PageActionMenu
+        v-if="overflowItems.length"
+        :items="overflowItems"
+      />
+      <slot name="utility">
+        <PageUtilityActions v-if="utility" />
+      </slot>
+    </div>
+  </div>
+</template>

package/src/components/PageUtilityActions.vue

@@ -0,0 +1,31 @@
+<script setup lang="ts">
+// Shipped as source: the consumer's Vite compiles this SFC. All imports are
+// explicit — no reliance on the consumer's auto-import configuration.
+// i18n key contract: pageChrome.help.
+// Utility triggers stay LABELED buttons (not icon-only) by convention.
+import { computed, inject } from 'vue'
+import { useI18n } from 'vue-i18n'
+import USeparator from '@nuxt/ui/components/Separator.vue'
+import UButton from '@nuxt/ui/components/Button.vue'
+import { HELP_PANEL_KEY } from '@octabits-io/nuxt-ui-kit'
+
+const { t } = useI18n()
+const helpPanel = inject(HELP_PANEL_KEY, null)
+
+const showHelp = computed(() => Boolean(helpPanel?.hasActions.value))
+</script>
+
+<template>
+  <div v-if="showHelp" class="flex items-center gap-1">
+    <USeparator orientation="vertical" class="h-5 mx-1" />
+    <UButton
+      v-if="helpPanel"
+      icon="i-lucide-circle-help"
+      :label="t('pageChrome.help')"
+      size="sm"
+      color="neutral"
+      :variant="helpPanel.isOpen.value ? 'soft' : 'ghost'"
+      @click="helpPanel.toggle()"
+    />
+  </div>
+</template>

package/src/components/SubSidebar.vue

@@ -28,6 +28,15 @@ const route = useRoute()
 
 const buttonLabel = computed(() => props.toggleLabel ?? props.title)
 
+// A named handler rather than an inline `@click="open = true"`: Vue compiles an
+// inline assignment to `$event => (open = true)`, whose return type is
+// `boolean`. UButton types `onClick` as `(event) => void | Promise<void>` — a
+// *union*, so TS's "a function returning a value is assignable to a void-returning
+// signature" rule does not apply and the assignment errors (TS2322).
+function openSidebar() {
+  open.value = true
+}
+
 watch(
   () => [route.path, route.query[props.selectionQueryKey]],
   () => { open.value = false },
@@ -73,7 +82,7 @@ watch(
             color="neutral"
             variant="outline"
             size="sm"
-            @click="open = true"
+            @click="openSidebar"
           />
         </div>
         <div class="min-w-0 flex-1 overflow-y-auto">

package/src/components/TranslationBadge.vue

@@ -0,0 +1,65 @@
+<script setup lang="ts">
+// Shipped as source: the consumer's Vite compiles this SFC. All imports are
+// explicit — no reliance on the consumer's auto-import configuration.
+// i18n key contract: localeField.translationStatus.complete / .missing.
+// Requires provideLocaleFieldContext() near the app root.
+import { computed, toValue } from 'vue'
+import { useI18n } from 'vue-i18n'
+import UTooltip from '@nuxt/ui/components/Tooltip.vue'
+import UBadge from '@nuxt/ui/components/Badge.vue'
+import UIcon from '@nuxt/ui/components/Icon.vue'
+import {
+  useLocaleFieldContext,
+  type TranslationStatus,
+} from '@octabits-io/nuxt-ui-kit/locale'
+
+/**
+ * Translation-completeness badge for list rows and detail headers.
+ *
+ * - Hidden for single-locale content (nothing to translate into).
+ * - Green check when every in-use translatable leaf covers all supported
+ *   locales (register variants inherit their base).
+ * - Orange with the total missing-leaf count otherwise; the tooltip breaks
+ *   the count down per locale.
+ */
+const props = defineProps<{
+  status: TranslationStatus | undefined
+}>()
+
+const { t } = useI18n()
+const { locales } = useLocaleFieldContext().useSource()
+
+const visible = computed(() => !!props.status && toValue(locales).length > 1)
+
+const totalMissing = computed(() =>
+  Object.values(props.status?.missing ?? {}).reduce((sum, n) => sum + n, 0),
+)
+
+const tooltip = computed(() => {
+  if (!props.status) return ''
+  if (props.status.complete) return t('localeField.translationStatus.complete')
+  const perLocale = Object.entries(props.status.missing)
+    .map(([locale, n]) => `${locale.toUpperCase()}: ${n}`)
+    .join(', ')
+  return t('localeField.translationStatus.missing', { details: perLocale })
+})
+</script>
+
+<template>
+  <UTooltip v-if="visible" :text="tooltip">
+    <UBadge
+      v-if="!status!.complete"
+      color="warning"
+      variant="subtle"
+      size="xs"
+      icon="i-lucide-languages"
+      :label="String(totalMissing)"
+    />
+    <UIcon
+      v-else
+      name="i-lucide-check-circle-2"
+      class="size-4 text-success"
+      :aria-label="t('localeField.translationStatus.complete')"
+    />
+  </UTooltip>
+</template>