@octabits-io/nuxt-ui-kit 0.7.0 → 0.9.0

package/dist/dates/index.d.ts

@@ -10,6 +10,11 @@ interface Period {
  * Example: `{ start: "2025-01-01", end: "2025-01-03" }` → 3 days.
  */
 declare function calculateDays(period: Period): number;
+/**
+ * Number of nights in a period whose `end` is **exclusive** (departure
+ * semantics). Example: `{ start: "2025-01-01", end: "2025-01-03" }` → 2 nights.
+ */
+declare function calculateNights(period: Period): number;
 /** Shift an ISO date string by n days; `''` stays `''`. */
 declare function shiftIso(iso: string, days: number): string;
 /**
@@ -39,4 +44,4 @@ declare function createDateFormatter(options: DateFormatterOptions): {
 };
 type DateFormatter = ReturnType<typeof createDateFormatter>;
 //#endregion
-export { DateFormatter, DateFormatterOptions, Period, calculateDays, createDateFormatter, shiftIso, useDateRangeInput };
+export { DateFormatter, DateFormatterOptions, Period, calculateDays, calculateNights, createDateFormatter, shiftIso, useDateRangeInput };

package/dist/dates/index.js

@@ -8,6 +8,13 @@ import { addDays, differenceInDays, eachDayOfInterval, format, parseISO } from "
 function calculateDays(period) {
 	return differenceInDays(new Date(period.end), new Date(period.start)) + 1;
 }
+/**
+* Number of nights in a period whose `end` is **exclusive** (departure
+* semantics). Example: `{ start: "2025-01-01", end: "2025-01-03" }` → 2 nights.
+*/
+function calculateNights(period) {
+	return differenceInDays(new Date(period.end), new Date(period.start));
+}
 /** Shift an ISO date string by n days; `''` stays `''`. */
 function shiftIso(iso, days) {
 	if (!iso || days === 0) return iso;
@@ -105,4 +112,4 @@ function createDateFormatter(options) {
 	};
 }
 //#endregion
-export { calculateDays, createDateFormatter, shiftIso, useDateRangeInput };
+export { calculateDays, calculateNights, createDateFormatter, shiftIso, useDateRangeInput };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@octabits-io/nuxt-ui-kit",
-  "version": "0.7.0",
+  "version": "0.9.0",
   "description": "Frontend kit for Nuxt/Vue admin SPAs: OIDC session harness (oidc-client-ts), Eden Treaty client factory, auth/org store cores, and a route-guard builder — factory-style seams the app wires into its own plugins, stores, and middleware",
   "license": "MIT",
   "type": "module",
@@ -75,7 +75,7 @@
     "vitest": "^4.1.10",
     "vue": "^3.5.40",
     "zod": "^4.4.3",
-    "@octabits-io/framework": "^0.4.0"
+    "@octabits-io/framework": "^0.7.0"
   },
   "peerDependencies": {
     "@elysiajs/eden": "^1.4.0",

package/src/components/FlexiblePeriodInput.vue

@@ -0,0 +1,238 @@
+<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.
+//
+// Flexible travel-period wish: a date *window* (earliest arrival → latest
+// departure) plus a desired stay length in nights — "between Jun 1 and
+// Jun 21 for 7 nights". Composes DateRangeInput (kind="travel") for the
+// window and adds a nights input, cross-field validation, and a metadata
+// line (window span, flexibility, example stay).
+//
+// i18n key contract: flexPeriod.* (earliestStart/latestEnd/nightsLabel/
+// clear/windowSpan/flexibility/example/errors.*) and period.travel.nights,
+// plus the composed DateRangeInput's dateRange.* keys.
+import { computed, watch } from 'vue'
+import { useI18n } from 'vue-i18n'
+import UInputNumber from '@nuxt/ui/components/InputNumber.vue'
+import UButton from '@nuxt/ui/components/Button.vue'
+import DateRangeInput from './DateRangeInput.vue'
+import {
+  calculateNights,
+  createDateFormatter,
+  shiftIso,
+  type Period,
+} from '@octabits-io/nuxt-ui-kit/dates'
+
+type InputSize = 'xs' | 'sm' | 'md' | 'lg' | 'xl'
+
+const props = withDefaults(defineProps<{
+  /**
+   * The wish window in travel semantics: `start` = earliest possible
+   * arrival, `end` = latest possible departure (ISO YYYY-MM-DD, `''` =
+   * unset). Unlike DateRangeInput's booking-space model, both bounds are
+   * literal calendar dates — conversion happens at the inner boundary.
+   */
+  modelValue: Period
+  /** Desired stay length in nights; `null` = unset. */
+  nights: number | null
+  minNights?: number
+  maxNights?: number
+  disabled?: boolean
+  size?: InputSize
+  /** Calendar trigger icon, passed through to the window inputs. */
+  icon?: string
+  startLabel?: string
+  endLabel?: string
+  /** Show the built-in clear (X) button when anything is set. */
+  clearable?: boolean
+}>(), {
+  minNights: 1,
+  maxNights: 365,
+  disabled: false,
+  size: 'md',
+  icon: undefined,
+  startLabel: undefined,
+  endLabel: undefined,
+  clearable: true,
+})
+
+const emit = defineEmits<{
+  'update:modelValue': [value: Period]
+  'update:nights': [value: number | null]
+  'change': [payload: { window: Period, nights: number | null, isValid: boolean }]
+}>()
+
+const { t, locale } = useI18n()
+const { formatDateMedium } = createDateFormatter({ getLocale: () => locale.value })
+
+const startAriaLabel = computed(() => props.startLabel || t('flexPeriod.earliestStart'))
+const endAriaLabel = computed(() => props.endLabel || t('flexPeriod.latestEnd'))
+
+// The inner DateRangeInput binds in booking semantics (end = last booked
+// day) and displays departure via kind="travel". Our model's end IS the
+// departure date, so convert ±1 day at this boundary only. shiftIso('')
+// stays '' — half-filled pairs pass through literally (never auto-fixed).
+const innerPeriod = computed<Period>({
+  get: () => ({
+    start: props.modelValue.start,
+    end: shiftIso(props.modelValue.end, -1),
+  }),
+  set: (v) => {
+    emit('update:modelValue', {
+      start: v.start,
+      end: shiftIso(v.end, 1),
+    })
+  },
+})
+
+const nightsValue = computed<number | null>({
+  get: () => props.nights,
+  set: v => emit('update:nights', v ?? null),
+})
+
+const hasAnyValue = computed(() =>
+  !!props.modelValue.start || !!props.modelValue.end || props.nights != null,
+)
+
+function clearAll() {
+  emit('update:modelValue', { start: '', end: '' })
+  emit('update:nights', null)
+}
+
+// --- Derived metadata ---
+
+const windowComplete = computed(() =>
+  !!props.modelValue.start
+  && !!props.modelValue.end
+  && props.modelValue.end > props.modelValue.start,
+)
+
+/** Nights the full window spans (arrival → departure, exclusive end). */
+const windowNights = computed<number | null>(() =>
+  windowComplete.value ? calculateNights(props.modelValue) : null,
+)
+
+/** Scheduling slack: how many nights the stay can shift inside the window. */
+const flexNights = computed<number | null>(() => {
+  if (windowNights.value === null || props.nights == null) return null
+  const flex = windowNights.value - props.nights
+  return flex > 0 ? flex : null
+})
+
+/** Example stay anchored at the earliest arrival, when start + nights known. */
+const exampleStay = computed(() => {
+  if (!props.modelValue.start || props.nights == null || props.nights < 1) return ''
+  // A stay that doesn't fit the window has no truthful example — the
+  // exceed-window error below explains the situation instead.
+  if (windowNights.value !== null && props.nights > windowNights.value) return ''
+  return t('flexPeriod.example', {
+    start: formatDateMedium(props.modelValue.start),
+    end: formatDateMedium(shiftIso(props.modelValue.start, props.nights)),
+  })
+})
+
+const metadataParts = computed<string[]>(() => {
+  const parts: string[] = []
+  if (windowNights.value !== null && windowNights.value > 0) {
+    parts.push(t('flexPeriod.windowSpan', { nights: t('period.travel.nights', windowNights.value) }))
+  }
+  if (flexNights.value !== null) {
+    parts.push(t('flexPeriod.flexibility', { nights: t('period.travel.nights', flexNights.value) }))
+  }
+  if (exampleStay.value) {
+    parts.push(exampleStay.value)
+  }
+  return parts
+})
+
+// --- Validation (nights axis only; window errors are the inner input's job) ---
+
+const nightsError = computed<string | null>(() => {
+  if (props.nights == null) return null
+  if (props.nights < props.minNights) {
+    return t('flexPeriod.errors.minNights', { n: props.minNights })
+  }
+  if (props.nights > props.maxNights) {
+    return t('flexPeriod.errors.maxNights', { n: props.maxNights })
+  }
+  if (windowNights.value !== null && props.nights > windowNights.value) {
+    return t('flexPeriod.errors.nightsExceedWindow', {
+      nights: t('period.travel.nights', props.nights),
+      window: t('period.travel.nights', windowNights.value),
+    })
+  }
+  return null
+})
+
+const nightsInputColor = computed<'error' | undefined>(() =>
+  nightsError.value !== null ? 'error' : undefined,
+)
+
+// A wish is progressive capture: fully empty is valid; a window, once
+// started, must be complete and ordered (in travel space, departure strictly
+// after arrival = at least one night).
+const windowValid = computed(() => {
+  const { start, end } = props.modelValue
+  if (!start && !end) return true
+  return windowComplete.value
+})
+
+const isValid = computed(() => windowValid.value && nightsError.value === null)
+
+watch(
+  () => [props.modelValue.start, props.modelValue.end, props.nights] as const,
+  ([start, end, nights]) => {
+    emit('change', { window: { start, end }, nights, isValid: isValid.value })
+  },
+)
+</script>
+
+<template>
+  <div class="flex flex-col gap-1">
+    <div class="flex items-start gap-2">
+      <DateRangeInput
+        v-model="innerPeriod"
+        kind="travel"
+        :disabled="disabled"
+        :size="size"
+        :icon="icon"
+        :start-label="startAriaLabel"
+        :end-label="endAriaLabel"
+        class="flex-1"
+      />
+      <UInputNumber
+        v-model="nightsValue"
+        :min="minNights"
+        :max="maxNights"
+        :size="size"
+        :disabled="disabled"
+        :color="nightsInputColor"
+        :aria-label="t('flexPeriod.nightsLabel')"
+        :placeholder="t('flexPeriod.nightsLabel')"
+        class="w-28 shrink-0"
+      />
+      <UButton
+        v-if="clearable && hasAnyValue"
+        icon="i-lucide-x"
+        color="neutral"
+        variant="ghost"
+        :size="size"
+        :disabled="disabled"
+        :aria-label="t('flexPeriod.clear')"
+        @click="clearAll"
+      />
+    </div>
+
+    <!-- Slot for a derived summary shown between the inputs and the hints,
+         matching DateRangeInput's slot for layout parity. -->
+    <slot name="summary" />
+
+    <p v-if="metadataParts.length" class="text-xs text-muted">
+      {{ metadataParts.join(' · ') }}
+    </p>
+
+    <p v-if="nightsError" class="text-sm text-error">
+      {{ nightsError }}
+    </p>
+  </div>
+</template>

package/src/components/PageAction.vue

@@ -30,25 +30,38 @@ const props = withDefaults(defineProps<{
   showLabel?: boolean
   /** Whether the tooltip should respect global disabled state. */
   tooltipDisabled?: boolean
+  /**
+   * Why the action is currently unavailable. When set, the button renders
+   * disabled and the tooltip shows "label — reason", keeping the action's
+   * purpose visible alongside the blocker. Hover on the disabled button works
+   * via an internal span wrapper (disabled buttons don't dispatch pointer
+   * events).
+   */
+  disabledReason?: string | null
 }>(), {
   tone: 'neutral',
   loading: false,
   disabled: false,
   showLabel: false,
   tooltipDisabled: false,
+  disabledReason: null,
 })
 
 const slots = useSlots()
 
 const hasLabelSlot = computed(() => Boolean(slots.default))
 const isIconOnly = computed(() => !hasLabelSlot.value && !props.showLabel)
+const isBlocked = computed(() => Boolean(props.disabledReason))
+const tooltipText = computed(() =>
+  props.disabledReason ? `${props.label} — ${props.disabledReason}` : props.label,
+)
 
 const buttonProps = computed<Partial<ButtonProps>>(() => {
   const base: Partial<ButtonProps> = {
     icon: props.icon,
     size: 'sm',
     loading: props.loading,
-    disabled: props.disabled || props.loading,
+    disabled: props.disabled || props.loading || isBlocked.value,
     to: props.to,
     target: props.target,
   }
@@ -72,8 +85,25 @@ if (import.meta.dev && !props.label) {
 </script>
 
 <template>
-  <UTooltip v-if="isIconOnly" :text="label" :disabled="tooltipDisabled">
+  <UTooltip
+    v-if="isIconOnly || isBlocked"
+    :text="tooltipText"
+    :disabled="!isBlocked && tooltipDisabled"
+  >
+    <!-- Disabled buttons don't dispatch pointer events: when blocked, the span
+         is the hover target and the button opts out of pointer events. -->
+    <span v-if="isBlocked" class="inline-flex">
+      <UButton
+        v-bind="buttonProps"
+        class="pointer-events-none"
+        :aria-label="tooltipText"
+        :label="!isIconOnly && showLabel ? label : undefined"
+      >
+        <slot v-if="!isIconOnly" />
+      </UButton>
+    </span>
     <UButton
+      v-else
       v-bind="buttonProps"
       :aria-label="label"
     />

package/src/components/PageHeader.vue

@@ -15,7 +15,10 @@ 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`.
+ * - State-changing decision actions (confirm, publish, cancel, …) render
+ *   labeled via `show-label`; generic reversible tools (edit, preview,
+ *   download, add) stay icon-only with tooltips.
+ * - Max 3 inline actions visible per state 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 =