kmcom-nuxt-layers 2.7.4 → 3.0.0

package/layers/core/app/components/ElementTw.vue

@@ -0,0 +1,86 @@
+<script setup lang="ts">
+  // computed() needs an explicit import here (rather than Nuxt's auto-import) so this
+  // component still mounts under vitest's 'vue' project, which has no Nuxt auto-import
+  // context — same tension as Element.vue's history/Group.vue/BaselineStatus.vue, exempted below.
+  import { computed } from 'vue'
+
+  import { useElementStyle } from '../composables/useElementStyle'
+  import type { ElementProps } from '../types/element'
+  import { styleToTailwindClasses } from '../utils/styleToTailwindClasses'
+
+  const {
+    as = 'div',
+    componentProps,
+    block,
+    flex,
+    grid: gridMode,
+    hidden,
+    cols,
+    rows,
+    gap,
+    align,
+    justify,
+    p,
+    px,
+    py,
+    m,
+    mx,
+    my,
+    w,
+    h,
+    minW,
+    maxW,
+    minH,
+    maxH,
+    aspect,
+    bg,
+    color,
+    border,
+    radius,
+    shadow,
+    cursor,
+    select,
+    pointer,
+  } = defineProps<ElementProps>()
+
+  const style = useElementStyle(() => ({
+    block,
+    flex,
+    grid: gridMode,
+    hidden,
+    cols,
+    rows,
+    gap,
+    align,
+    justify,
+    p,
+    px,
+    py,
+    m,
+    mx,
+    my,
+    w,
+    h,
+    minW,
+    maxW,
+    minH,
+    maxH,
+    aspect,
+    bg,
+    color,
+    border,
+    radius,
+    shadow,
+    cursor,
+    select,
+    pointer,
+  }))
+
+  const twClasses = computed(() => styleToTailwindClasses(style.value))
+</script>
+
+<template>
+  <component :is="as" v-bind="componentProps" :class="twClasses">
+    <slot />
+  </component>
+</template>

package/layers/core/app/components/LoadingScreen.vue

@@ -11,10 +11,6 @@
   const { isLoading, progress } = useLoading()
   const config = useAppConfig()
 
-  // Debug logs
-  // console.log('[LoadingScreen] Component created!')
-  // console.log('[LoadingScreen] Initial - isLoading:', isLoading.value, 'progress:', progress.value)
-
   // Type-safe access to loading config
   const loadingConfig = computed(() => {
     const coreLayer = config.coreLayer as { loading?: LoadingConfig }
@@ -37,21 +33,10 @@
   watch(
     [isLoading, progress],
     ([loading, prog]) => {
-      // console.log(
-      //   '[LoadingScreen] Watch fired - isLoading:',
-      //   loading,
-      //   'progress:',
-      //   prog,
-      //   'visible:',
-      //   visible.value
-      // )
-
       if (!loading && prog >= 100 && !hasFinished.value) {
         hasFinished.value = true
-        // console.log('[LoadingScreen] Loading finished! Will hide after', minDuration.value, 'ms')
 
         setTimeout(() => {
-          // console.log('[LoadingScreen] Hiding now')
           visible.value = false
         }, minDuration.value)
       }

package/layers/core/app/composables/useElementGrid.test.ts

@@ -0,0 +1,33 @@
+import { describe, expect, it } from 'vitest'
+
+import { useElementGrid } from './useElementGrid'
+
+describe('useElementGrid container axis', () => {
+  it('returns no grid-template properties when grid is not set', () => {
+    const result = useElementGrid({ cols: 12 })
+    expect(result.gridTemplateColumns).toBeUndefined()
+    expect(result.gridTemplateRows).toBeUndefined()
+  })
+
+  it('converts a numeric cols to a repeat() track when grid is set', () => {
+    const result = useElementGrid({ grid: true, cols: 12 })
+    expect(result.gridTemplateColumns).toBe('repeat(12, 1fr)')
+  })
+
+  it('converts a numeric rows to a repeat() track when grid is set', () => {
+    const result = useElementGrid({ grid: true, rows: 4 })
+    expect(result.gridTemplateRows).toBe('repeat(4, 1fr)')
+  })
+
+  it('passes a string cols track through unchanged', () => {
+    const result = useElementGrid({ grid: true, cols: '1fr 2fr 1fr' })
+    expect(result.gridTemplateColumns).toBe('1fr 2fr 1fr')
+  })
+
+  // display is intentionally NOT set by useElementGrid — useElementLayout owns
+  // the hidden > grid > flex > block display priority.
+  it('never sets display, even when grid is true', () => {
+    const result = useElementGrid({ grid: true, cols: 12 })
+    expect(result.display).toBeUndefined()
+  })
+})

package/layers/core/app/composables/useElementGrid.ts

@@ -0,0 +1,29 @@
+import type { CSSProperties } from 'vue'
+
+// `| undefined` on each is explicit (not just `?`) so component prop objects
+// — which have it too, under exactOptionalPropertyTypes — are assignable here.
+export type ElementGridProps = {
+  grid?: boolean | undefined
+  cols?: number | string | undefined
+  rows?: number | string | undefined
+}
+
+function track(value: number | string | undefined): string | undefined {
+  return typeof value === 'number' ? `repeat(${value}, 1fr)` : value
+}
+
+// Container axis only ("I am a grid"). Item placement (colStart/colSpan/rowStart/
+// rowSpan) is deliberately out of scope here — that engine (buildGridPlacementStyle,
+// layers/structure/layout) lives in the layout layer, and Element itself lives in
+// core (used across every layer) so it can't depend on layout. Use LayoutGridItem
+// directly for item placement inside a grid built with Element.
+export function useElementGrid(props: ElementGridProps): Partial<CSSProperties> {
+  return {
+    // `display` is intentionally NOT set here — useElementLayout already maps
+    // grid: true -> display: 'grid' and owns the hidden > grid > flex > block priority.
+    ...(props.grid && {
+      gridTemplateColumns: track(props.cols),
+      gridTemplateRows: track(props.rows),
+    }),
+  }
+}

package/layers/core/app/composables/useElementInteraction.test.ts

@@ -0,0 +1,27 @@
+import { describe, expect, it } from 'vitest'
+
+import { useElementInteraction } from './useElementInteraction'
+
+describe('useElementInteraction', () => {
+  it('returns all-undefined style when no props are set', () => {
+    expect(useElementInteraction({})).toEqual({
+      cursor: undefined,
+      userSelect: undefined,
+      pointerEvents: undefined,
+    })
+  })
+
+  it('maps every prop to its CSS property 1:1', () => {
+    expect(
+      useElementInteraction({
+        cursor: 'pointer',
+        select: 'none',
+        pointer: 'none',
+      })
+    ).toEqual({
+      cursor: 'pointer',
+      userSelect: 'none',
+      pointerEvents: 'none',
+    })
+  })
+})

package/layers/core/app/composables/useElementInteraction.ts

@@ -0,0 +1,17 @@
+import type { CSSProperties } from 'vue'
+
+// `| undefined` on each is explicit (not just `?`) so component prop objects
+// — which have it too, under exactOptionalPropertyTypes — are assignable here.
+export type ElementInteractionProps = {
+  cursor?: CSSProperties['cursor'] | undefined
+  select?: CSSProperties['userSelect'] | undefined
+  pointer?: CSSProperties['pointerEvents'] | undefined
+}
+
+export function useElementInteraction(props: ElementInteractionProps): Partial<CSSProperties> {
+  return {
+    cursor: props.cursor,
+    userSelect: props.select,
+    pointerEvents: props.pointer,
+  }
+}

package/layers/core/app/composables/useElementLayout.test.ts

@@ -0,0 +1,41 @@
+import { describe, expect, it } from 'vitest'
+
+import { useElementLayout } from './useElementLayout'
+
+describe('useElementLayout', () => {
+  it('returns no display when no mode prop is set', () => {
+    expect(useElementLayout({})).toEqual({ display: undefined })
+  })
+
+  it('resolves block to display: block', () => {
+    expect(useElementLayout({ block: true })).toEqual({ display: 'block' })
+  })
+
+  it('resolves flex to display: flex', () => {
+    expect(useElementLayout({ flex: true })).toEqual({ display: 'flex' })
+  })
+
+  it('resolves grid to display: grid', () => {
+    expect(useElementLayout({ grid: true })).toEqual({ display: 'grid' })
+  })
+
+  it('resolves hidden to display: none', () => {
+    expect(useElementLayout({ hidden: true })).toEqual({ display: 'none' })
+  })
+
+  it('prioritizes hidden over grid, flex, and block when multiple are set', () => {
+    expect(useElementLayout({ hidden: true, grid: true, flex: true, block: true })).toEqual({
+      display: 'none',
+    })
+  })
+
+  it('prioritizes grid over flex and block', () => {
+    expect(useElementLayout({ grid: true, flex: true, block: true })).toEqual({
+      display: 'grid',
+    })
+  })
+
+  it('prioritizes flex over block', () => {
+    expect(useElementLayout({ flex: true, block: true })).toEqual({ display: 'flex' })
+  })
+})

package/layers/core/app/composables/useElementLayout.ts

@@ -0,0 +1,26 @@
+import type { CSSProperties } from 'vue'
+
+// `| undefined` on each is explicit (not just `?`) so component prop objects
+// — which have it too, under exactOptionalPropertyTypes — are assignable here.
+export type ElementLayoutProps = {
+  block?: boolean | undefined
+  flex?: boolean | undefined
+  grid?: boolean | undefined
+  hidden?: boolean | undefined
+}
+
+type Mode = 'hidden' | 'grid' | 'flex' | 'block'
+
+const DISPLAY_FOR: Record<Mode, CSSProperties['display']> = {
+  hidden: 'none',
+  grid: 'grid',
+  flex: 'flex',
+  block: 'block',
+}
+
+export function useElementLayout(props: ElementLayoutProps): Partial<CSSProperties> {
+  const mode = (['hidden', 'grid', 'flex', 'block'] as const).find((m) => props[m])
+  return {
+    display: mode && DISPLAY_FOR[mode],
+  }
+}

package/layers/core/app/composables/useElementSizing.test.ts

@@ -0,0 +1,39 @@
+import { describe, expect, it } from 'vitest'
+
+import { useElementSizing } from './useElementSizing'
+
+describe('useElementSizing', () => {
+  it('returns all-undefined style when no props are set', () => {
+    expect(useElementSizing({})).toEqual({
+      width: undefined,
+      height: undefined,
+      minWidth: undefined,
+      maxWidth: undefined,
+      minHeight: undefined,
+      maxHeight: undefined,
+      aspectRatio: undefined,
+    })
+  })
+
+  it('maps every prop to its CSS property 1:1', () => {
+    expect(
+      useElementSizing({
+        w: '80px',
+        h: '40px',
+        minW: '10rem',
+        maxW: '20rem',
+        minH: '5rem',
+        maxH: '15rem',
+        aspect: '16 / 9',
+      })
+    ).toEqual({
+      width: '80px',
+      height: '40px',
+      minWidth: '10rem',
+      maxWidth: '20rem',
+      minHeight: '5rem',
+      maxHeight: '15rem',
+      aspectRatio: '16 / 9',
+    })
+  })
+})

package/layers/core/app/composables/useElementSizing.ts

@@ -0,0 +1,25 @@
+import type { CSSProperties } from 'vue'
+
+// `| undefined` on each is explicit (not just `?`) so component prop objects
+// — which have it too, under exactOptionalPropertyTypes — are assignable here.
+export type ElementSizingProps = {
+  w?: CSSProperties['width'] | undefined
+  h?: CSSProperties['height'] | undefined
+  minW?: CSSProperties['minWidth'] | undefined
+  maxW?: CSSProperties['maxWidth'] | undefined
+  minH?: CSSProperties['minHeight'] | undefined
+  maxH?: CSSProperties['maxHeight'] | undefined
+  aspect?: CSSProperties['aspectRatio'] | undefined
+}
+
+export function useElementSizing(props: ElementSizingProps): Partial<CSSProperties> {
+  return {
+    width: props.w,
+    height: props.h,
+    minWidth: props.minW,
+    maxWidth: props.maxW,
+    minHeight: props.minH,
+    maxHeight: props.maxH,
+    aspectRatio: props.aspect,
+  }
+}

package/layers/core/app/composables/useElementStyle.ts

@@ -0,0 +1,65 @@
+import { computed, type ComputedRef, type CSSProperties } from 'vue'
+
+import type { ElementProps } from '../types/element'
+import { useElementGrid } from './useElementGrid'
+import { useElementInteraction } from './useElementInteraction'
+import { useElementLayout } from './useElementLayout'
+import { useElementSizing } from './useElementSizing'
+import { useElementSurface } from './useElementSurface'
+import { useLayoutAttrs } from './useLayoutAttrs'
+
+/**
+ * Merges the 5 element composables + core's useLayoutAttrs into one style
+ * object — the vocabulary shared by both Element (inline :style) and
+ * ElementTw (Tailwind arbitrary-property classes). Takes a getter (not the
+ * values directly) so callers can pass their own destructured defineProps
+ * bindings and keep reactivity, same as useLayoutAttrs's own getter param.
+ */
+export function useElementStyle(
+  getProps: () => Omit<ElementProps, 'as' | 'componentProps'>
+): ComputedRef<CSSProperties> {
+  return computed(() => {
+    const props = getProps()
+    return {
+      ...useElementLayout({
+        block: props.block,
+        flex: props.flex,
+        grid: props.grid,
+        hidden: props.hidden,
+      }),
+      ...useLayoutAttrs(() => ({
+        gap: props.gap,
+        align: props.align,
+        justify: props.justify,
+        p: props.p,
+        px: props.px,
+        py: props.py,
+        m: props.m,
+        mx: props.mx,
+        my: props.my,
+      })).style.value,
+      ...useElementGrid({ grid: props.grid, cols: props.cols, rows: props.rows }),
+      ...useElementSizing({
+        w: props.w,
+        h: props.h,
+        minW: props.minW,
+        maxW: props.maxW,
+        minH: props.minH,
+        maxH: props.maxH,
+        aspect: props.aspect,
+      }),
+      ...useElementSurface({
+        bg: props.bg,
+        color: props.color,
+        border: props.border,
+        radius: props.radius,
+        shadow: props.shadow,
+      }),
+      ...useElementInteraction({
+        cursor: props.cursor,
+        select: props.select,
+        pointer: props.pointer,
+      }),
+    }
+  })
+}

package/layers/core/app/composables/useElementSurface.test.ts

@@ -0,0 +1,33 @@
+import { describe, expect, it } from 'vitest'
+
+import { useElementSurface } from './useElementSurface'
+
+describe('useElementSurface', () => {
+  it('returns all-undefined style when no props are set', () => {
+    expect(useElementSurface({})).toEqual({
+      background: undefined,
+      color: undefined,
+      border: undefined,
+      borderRadius: undefined,
+      boxShadow: undefined,
+    })
+  })
+
+  it('maps every prop to its CSS property 1:1', () => {
+    expect(
+      useElementSurface({
+        bg: 'var(--ui-bg-elevated)',
+        color: 'var(--ui-text)',
+        border: '1px solid var(--ui-border)',
+        radius: '0.5rem',
+        shadow: '0 4px 12px rgb(0 0 0 / 0.15)',
+      })
+    ).toEqual({
+      background: 'var(--ui-bg-elevated)',
+      color: 'var(--ui-text)',
+      border: '1px solid var(--ui-border)',
+      borderRadius: '0.5rem',
+      boxShadow: '0 4px 12px rgb(0 0 0 / 0.15)',
+    })
+  })
+})

package/layers/core/app/composables/useElementSurface.ts

@@ -0,0 +1,21 @@
+import type { CSSProperties } from 'vue'
+
+// `| undefined` on each is explicit (not just `?`) so component prop objects
+// — which have it too, under exactOptionalPropertyTypes — are assignable here.
+export type ElementSurfaceProps = {
+  bg?: CSSProperties['background'] | undefined
+  color?: CSSProperties['color'] | undefined
+  border?: CSSProperties['border'] | undefined
+  radius?: CSSProperties['borderRadius'] | undefined
+  shadow?: CSSProperties['boxShadow'] | undefined
+}
+
+export function useElementSurface(props: ElementSurfaceProps): Partial<CSSProperties> {
+  return {
+    background: props.bg,
+    color: props.color,
+    border: props.border,
+    borderRadius: props.radius,
+    boxShadow: props.shadow,
+  }
+}

package/layers/core/app/composables/useErrorLog.ts

@@ -48,11 +48,13 @@ export function useErrorLog() {
   const appConfig = useAppConfig()
   const route = useRoute()
 
+  const errorConfig = (appConfig.coreLayer as { errors?: ErrorLogConfig } | undefined)?.errors
+
   const config = computed(() => ({
-    logToConsole: appConfig.coreLayer?.errors?.logToConsole ?? true,
-    logToExternal: appConfig.coreLayer?.errors?.logToExternal ?? false,
-    externalUrl: appConfig.coreLayer?.errors?.externalUrl,
-    externalToken: appConfig.coreLayer?.errors?.externalToken,
+    logToConsole: errorConfig?.logToConsole ?? true,
+    logToExternal: errorConfig?.logToExternal ?? false,
+    externalUrl: errorConfig?.externalUrl,
+    externalToken: errorConfig?.externalToken,
   }))
 
   /**

package/layers/core/app/composables/useLayoutAttrs.test.ts

@@ -0,0 +1,47 @@
+import { describe, expect, it } from 'vitest'
+
+import { useLayoutAttrs } from './useLayoutAttrs'
+
+describe('useLayoutAttrs margin support', () => {
+  it('sets margin from a static token', () => {
+    const { style } = useLayoutAttrs(() => ({ m: 'md' }))
+    expect(style.value.margin).toBe('var(--fluid-space-md)')
+  })
+
+  it('sets marginInline from px-equivalent mx', () => {
+    const { style } = useLayoutAttrs(() => ({ mx: 'lg' }))
+    expect(style.value.marginInline).toBe('var(--fluid-space-lg)')
+  })
+
+  it('sets marginBlock from my', () => {
+    const { style } = useLayoutAttrs(() => ({ my: 'sm' }))
+    expect(style.value.marginBlock).toBe('var(--fluid-space-sm)')
+  })
+
+  it('resolves none to 0px for margin', () => {
+    const { style } = useLayoutAttrs(() => ({ m: 'none' }))
+    expect(style.value.margin).toBe('0px')
+  })
+
+  it('omits margin keys entirely when not passed', () => {
+    const { style } = useLayoutAttrs(() => ({ gap: 'md' }))
+    expect(style.value.margin).toBeUndefined()
+    expect(style.value.marginInline).toBeUndefined()
+    expect(style.value.marginBlock).toBeUndefined()
+  })
+
+  it('does not regress existing gap/align/justify/padding behavior', () => {
+    const { style } = useLayoutAttrs(() => ({
+      gap: 'md',
+      align: 'center',
+      justify: 'between',
+      p: 'lg',
+    }))
+    expect(style.value).toEqual({
+      gap: 'var(--fluid-space-md)',
+      padding: 'var(--fluid-space-lg)',
+      alignItems: 'center',
+      justifyContent: 'space-between',
+    })
+  })
+})

package/layers/core/app/composables/useLayoutAttrs.ts

@@ -0,0 +1,94 @@
+import { computed, toValue, type ComputedRef, type CSSProperties, type MaybeRefOrGetter } from 'vue'
+
+import type { ResponsiveValue } from '../types/responsive'
+import type { Spacing } from '../types/tokens'
+
+export type Align = 'start' | 'center' | 'end' | 'stretch' | 'baseline'
+export type Justify = 'start' | 'center' | 'end' | 'between' | 'around' | 'evenly'
+
+// `| undefined` on each is explicit (not just `?`) so component prop objects
+// — which have it too, under exactOptionalPropertyTypes — are assignable here.
+export type LayoutAttrsInput = {
+  gap?: ResponsiveValue<Spacing> | Spacing | undefined
+  align?: ResponsiveValue<Align> | Align | undefined
+  justify?: ResponsiveValue<Justify> | Justify | undefined
+  p?: ResponsiveValue<Spacing> | Spacing | undefined
+  px?: ResponsiveValue<Spacing> | Spacing | undefined
+  py?: ResponsiveValue<Spacing> | Spacing | undefined
+  m?: ResponsiveValue<Spacing> | Spacing | undefined
+  mx?: ResponsiveValue<Spacing> | Spacing | undefined
+  my?: ResponsiveValue<Spacing> | Spacing | undefined
+}
+
+const ALIGN_MAP: Record<Align, string> = {
+  start: 'flex-start',
+  center: 'center',
+  end: 'flex-end',
+  stretch: 'stretch',
+  baseline: 'baseline',
+}
+
+const JUSTIFY_MAP: Record<Justify, string> = {
+  start: 'flex-start',
+  center: 'center',
+  end: 'flex-end',
+  between: 'space-between',
+  around: 'space-around',
+  evenly: 'space-evenly',
+}
+
+// ponytail: only `default` is resolved — gap/align/justify/p are continuous
+// or low-stakes enough that a breakpoint jump isn't a real need yet (see
+// spec §15). Add sm/md/lg/xl handling here (CSS custom properties + media
+// queries, since this returns inline style) if a primitive actually needs it.
+function resolveDefault<T>(value: ResponsiveValue<T> | T | undefined): T | undefined {
+  const isResponsiveObject = typeof value === 'object' && value !== null && 'default' in value
+  return isResponsiveObject ? (value as ResponsiveValue<T>).default : (value as T | undefined)
+}
+
+function spacingVar(token: Spacing): string {
+  return token === 'none' ? '0px' : `var(--fluid-space-${token})`
+}
+
+function applySpacing(
+  result: CSSProperties,
+  cssProp:
+    | 'gap'
+    | 'padding'
+    | 'paddingInline'
+    | 'paddingBlock'
+    | 'margin'
+    | 'marginInline'
+    | 'marginBlock',
+  value: ResponsiveValue<Spacing> | Spacing | undefined
+): void {
+  const resolved = resolveDefault(value)
+  if (resolved) result[cssProp] = spacingVar(resolved)
+}
+
+export function useLayoutAttrs(input: MaybeRefOrGetter<LayoutAttrsInput>): {
+  style: ComputedRef<CSSProperties>
+} {
+  const style = computed((): CSSProperties => {
+    const { gap, align, justify, p, px, py, m, mx, my } = toValue(input)
+    const result: CSSProperties = {}
+
+    applySpacing(result, 'gap', gap)
+    applySpacing(result, 'padding', p)
+    applySpacing(result, 'paddingInline', px)
+    applySpacing(result, 'paddingBlock', py)
+    applySpacing(result, 'margin', m)
+    applySpacing(result, 'marginInline', mx)
+    applySpacing(result, 'marginBlock', my)
+
+    const resolvedAlign = resolveDefault(align)
+    if (resolvedAlign) result.alignItems = ALIGN_MAP[resolvedAlign]
+
+    const resolvedJustify = resolveDefault(justify)
+    if (resolvedJustify) result.justifyContent = JUSTIFY_MAP[resolvedJustify]
+
+    return result
+  })
+
+  return { style }
+}

package/layers/core/app/composables/useLoading.ts

@@ -20,7 +20,9 @@ const _timers = {
  */
 export function useLoading() {
   const appConfig = useAppConfig()
-  const isLoading = useState('core:loading', () => appConfig.coreLayer?.loading?.enabled !== false)
+  const loadingConfig = (appConfig.coreLayer as { loading?: { enabled?: boolean } } | undefined)
+    ?.loading
+  const isLoading = useState('core:loading', () => loadingConfig?.enabled !== false)
   const progress = useState('core:loading:progress', () => 0)
 
   function startLoading(): void {