@livestorm/ui-vue 3.0.0 → 4.0.0

package/src/components/UiPage/UiPage.vue

@@ -55,13 +55,6 @@ type HeadroomGap = keyof typeof HEADROOM_GAP_PX
 const DEFAULT_HEADROOM_GAP: HeadroomGap = 'md'
 
 const props = withDefaults(defineProps<{
-  /**
-   * Extra classes for the inner content `<section>`. Use to override the
-   * default surface, e.g. `bg-surface-neutral-300` instead of the standard
-   * `bg-surface-neutral-bg-main`. Appended after the defaults so it wins on
-   * conflicting utilities.
-   */
-  pageContentClasses?: string
   /**
    * Page title surfaced as the label of UiShell's fallback mobile menu topbar
    * (shown on a headerless page that has a side menu). Lets a page name its
@@ -69,14 +62,60 @@ const props = withDefaults(defineProps<{
    */
   title?: string
   /**
-   * The shape of the page inside the content card.
-   * - `document` (default): the card scrolls as a single column. The common
-   *   dashboard page — lists, forms, detail views.
+   * The shape of the page inside the content card. Padded shapes use the
+   * page padding P (16px below md, 24px from md), which the page exposes to
+   * its content as `var(--ui-page-padding)`. P applies inside the card only:
+   * the page header and the tabs above it keep their own spacing.
+   * - `document` (default): the card scrolls as a single column and pads
+   *   its content with P on every side. Forms, settings, content blocks.
+   * - `list`: like `document`, but the content is padded with P at the top
+   *   only: toolbars, tables and pagination run from card edge to card edge
+   *   and pad their sides with `--ui-page-inline`. The content is held to the
+   *   card height, so a child that may shrink (`flex-1 min-h-0`) becomes the
+   *   scroll region and a table header in it stays in view; anything taller
+   *   still scrolls the card.
    * - `app`: the card fills the available height and never scrolls itself;
-   *   the page owns its own scroll regions. For editor-style pages (split
-   *   panes, canvases) that would otherwise opt out of UiPage entirely.
+   *   the page owns its scroll regions and layout, so the content is not
+   *   padded. Each region pads itself with `var(--ui-page-padding)`.
+   *
+   * Edge-to-edge bands (toolbars, pagination) read `--ui-page-inline` for
+   * their side padding. UiDataTable pads its scroll region with it, so a
+   * wide table scrolls from card edge to card edge. It is set to P on a
+   * `list` page only and left unset everywhere else, so a band
+   * picks its inset with one class:
+   * - `px-(--ui-page-inline)`: P on a list page, 0 elsewhere.
+   * - `px-(--ui-page-inline,var(--spacing-space-4))`: P on a list page, the
+   *   band's own inset elsewhere.
+   *
+   * A page with a `leftSlot` keeps the split layout insets instead of P: its
+   * header slot aligns with the aside, not with the content.
    */
-  variant?: 'document' | 'app'
+  variant?: 'document' | 'list' | 'app'
+  /**
+   * Column split when a leftSlot is present: `third` (default) gives the
+   * aside 1/3 and the card 2/3; `half` splits them evenly; `fill` lets the
+   * aside take all remaining width while the card hugs its content — for
+   * app pages whose card is a fixed-width side panel (e.g. the room's
+   * interactions sidepane).
+   */
+  leftSlotRatio?: 'third' | 'half' | 'fill'
+  /**
+   * How the content card sits in the frame.
+   * - `anchored` (default): the dashboard page card — flush to the bottom and
+   *   right edges, rounded top-left, page-card chrome (level-3 elevation).
+   * - `floating`: a detached card with a thin gutter on every side, rounded
+   *   all around, elevated-card chrome (level-2 elevation + inner glow +
+   *   container border). The room's panel treatment.
+   */
+  frame?: 'anchored' | 'floating'
+  /**
+   * Viewport gate for the leftSlot: `lg` (default) renders the aside only
+   * from the lg breakpoint — the dashboard behavior, where the aside is
+   * secondary. `none` keeps the aside at every width, for app pages whose
+   * aside is primary content (the room's stage, the lobby's session
+   * information) and must never unmount with the viewport.
+   */
+  leftSlotBreakpoint?: 'lg' | 'none'
   /**
    * Headroom above the content card, letting the shell background show
    * through. Sizes map to px via `HEADROOM_GAP_PX`.
@@ -87,28 +126,85 @@ const props = withDefaults(defineProps<{
    * on a page that would otherwise get the default.
    */
   headroomGap?: HeadroomGap
+  /**
+   * Drops the content padding a `document` or `list` page gets by default, so the
+   * page's content reaches the card edges. Only for pages whose layout is
+   * edge-to-edge by design: full-bleed bands, or scroll regions that must
+   * sit against the card edge. Has no effect on `app` pages, which never get
+   * the padding.
+   */
+  flush?: boolean
+  /**
+   * The fill of an anchored content card.
+   * - `container` (default): the white content surface.
+   * - `background`: the grey page background, for screens whose content is
+   *   already cards or regions, so they do not sit in a second white box.
+   * A floating card keeps its elevated fill.
+   */
+  surface?: 'container' | 'background'
 }>(), {
-  pageContentClasses: '',
   title: undefined,
   variant: 'document',
+  leftSlotRatio: 'third',
+  frame: 'anchored',
+  leftSlotBreakpoint: 'lg',
   headroomGap: undefined,
+  flush: false,
+  surface: 'container',
 })
 
 const slots = defineSlots<{
   banner?(): Slot
   pageHeader?(): Slot
   pageTabs?(): Slot
+  /**
+   * Summary on the page background, between the page header (and tabs) and
+   * the content card, e.g. stat cards. It shares the page header's edges.
+   */
+  pageSummary?(): Slot
   leftSlot?(): Slot
   header?(): Slot
   footer?(): Slot
   default?(): Slot
 }>()
 
-// An `app` page manages its own scrolling, so every level from the page
-// content down to the card must stop scrolling and stop growing past the
-// viewport — otherwise a split-pane editor gets a second, outer scrollbar.
+// An `app` page manages its own scrolling: the card clips and its row is
+// pinned to the viewport, otherwise a split-pane editor gets a second, outer scrollbar.
 const isApp = computed(() => props.variant === 'app')
 const scrollClass = computed(() => (isApp.value ? 'overflow-hidden' : 'overflow-y-auto'))
+const fillsCard = computed(() => isApp.value || props.variant === 'list')
+
+// Spelled out as literals: Tailwind only generates classes it can see as
+// complete strings in the source.
+const pageColumnsClass = computed(() => {
+  const gated = props.leftSlotBreakpoint === 'lg'
+  if (props.leftSlotRatio === 'half') {
+    return gated ? 'has-[>:nth-child(2)]:lg:grid-cols-[1fr_1fr]' : 'has-[>:nth-child(2)]:grid-cols-[1fr_1fr]'
+  }
+  if (props.leftSlotRatio === 'fill') {
+    return gated ? 'has-[>:nth-child(2)]:lg:grid-cols-[minmax(0,1fr)_auto]' : 'has-[>:nth-child(2)]:grid-cols-[minmax(0,1fr)_auto]'
+  }
+  return gated ? 'has-[>:nth-child(2)]:lg:grid-cols-[1fr_2fr]' : 'has-[>:nth-child(2)]:grid-cols-[1fr_2fr]'
+})
+
+// Frame treatment. The chrome pairs are exclusive per frame (never merged),
+// so conflicting utilities can't race on stylesheet order.
+const isFloating = computed(() => props.frame === 'floating')
+const frameGutterClass = computed(() => (isFloating.value ? 'p-1 gap-x-1' : 'lg:gap-x-8'))
+const cardRadiusClass = computed(() => (isFloating.value ? 'rounded-container' : 'rounded-tl-container'))
+// Anchored keeps the page-card chrome: shadow-elevation-level-3 keeps
+// drop-shadow-2xl's exact geometry and light-mode colors, but its colors
+// resolve to transparent in dark content mode — the card no longer draws a
+// dark ring on the dark shell. Floating takes the elevated-card treatment
+// from the elevation proposal (level 2 + inner glow + container border).
+const anchoredFillClass = computed(() => (
+  props.surface === 'background' ? 'bg-surface-neutral-300' : 'bg-surface-neutral-bg-main'
+))
+const cardChromeClass = computed(() => (
+  isFloating.value
+    ? 'bg-elevation-2 shadow-elevation-level-2 inset-shadow-inner-glow border border-container-border'
+    : `${anchoredFillClass.value} shadow-elevation-level-3`
+))
 
 // Check for slot presence
 const bannerSlot = computed(() => !!slots.banner)
@@ -118,13 +214,55 @@ const leftSlot = computed(() => !!slots.leftSlot)
 const headerSlot = computed(() => !!slots.header)
 const footerSlot = computed(() => !!slots.footer)
 
-// Row track for the card grid. An `app` page needs its main row to take the
+const PAGE_INSETS = {
+  header: 'px-(--ui-page-padding) pt-(--ui-page-padding)',
+  headerBottom: 'pb-(--ui-page-padding)',
+  content: 'p-(--ui-page-padding)',
+}
+// A split page aligns its header with the aside rather than with the content.
+const SPLIT_INSETS = {
+  header: 'px-4 pt-4 lg:px-10 lg:pt-8',
+  headerBottom: 'pb-4 lg:pb-8',
+  content: 'px-4 py-4 lg:px-10 lg:pt-8 lg:pb-10',
+}
+const isSplitLayout = computed(() => leftSlot.value)
+// The header slot and the content share one side inset so their left edges align.
+const insets = computed(() => (isSplitLayout.value ? SPLIT_INSETS : PAGE_INSETS))
+
+const pageInlineClass = computed(() => (props.variant === 'list' ? '[--ui-page-inline:var(--ui-page-padding)]' : ''))
+
+const isContentPadded = computed(() => !isApp.value && !props.flush)
+const contentPaddingClass = computed(() => {
+  if (!isContentPadded.value) return ''
+  return props.variant === 'list' ? 'pt-(--ui-page-padding)' : insets.value.content
+})
+// The padded content's top padding already spaces it from the header.
+const headerBottomPaddingClass = computed(() => (isContentPadded.value ? '' : insets.value.headerBottom))
+
+// Who scrolls: the page-content row, or the card inside it?
+// - `app`: neither — the page owns its scroll regions. The row is pinned to the
+//   viewport but left unclipped, or it would eat the card's elevation shadow.
+// - leftSlot layout: the row. The aside can be taller than the viewport and
+//   scrolls together with the card (historical auth-page behavior). The 1px
+//   top padding keeps the card's elevation ring inside the scrollport.
+// - plain `document`: the card. Its row is pinned to the viewport height
+//   (minmax(0,1fr)) so the card's own overflow-y-auto engages, and the row
+//   stays unclipped — a scrollport would clip the card's elevation shadow
+//   at the flush edges.
+const pageContentScrollClass = computed(() => {
+  if (isApp.value) return 'overflow-visible grid-rows-[minmax(0,1fr)]'
+  return leftSlot.value
+    ? 'overflow-y-auto pt-px'
+    : 'overflow-visible grid-rows-[minmax(0,1fr)]'
+})
+
+// Row track for the card grid. An `app` or `list` page needs its main row to take the
 // leftover height and be allowed to shrink (minmax(0,1fr)), so nested
 // overflow containers resolve against a real height instead of growing.
 // Spelled out as literals: Tailwind only generates classes it can see as
 // complete strings in the source.
 const cardRowsClass = computed(() => {
-  if (!isApp.value) { return headerSlot.value ? 'grid-rows-[min-content]' : '' }
+  if (!fillsCard.value) { return headerSlot.value ? 'grid-rows-[min-content]' : '' }
   if (headerSlot.value && footerSlot.value) { return 'grid-rows-[min-content_minmax(0,1fr)_min-content]' }
   if (headerSlot.value) { return 'grid-rows-[min-content_minmax(0,1fr)]' }
   if (footerSlot.value) { return 'grid-rows-[minmax(0,1fr)_min-content]' }
@@ -164,7 +302,9 @@ if (!app) {
 // Prefer the app-installed $responsive (it may carry custom flags); fall
 // back to the shared singleton so no plugin registration is required.
 const responsive = computed(() => app.appContext.config.globalProperties.$responsive ?? useResponsive())
-const displayLeftSlot = computed(() => responsive.value.width >= BREAKPOINT_LG)
+const displayLeftSlot = computed(() => (
+  props.leftSlotBreakpoint === 'none' || responsive.value.width >= BREAKPOINT_LG
+))
 
 const UiPage = ref<HTMLElement | undefined>()
 const PageContent = ref<HTMLElement | undefined>()
@@ -179,7 +319,10 @@ const { contentMode } = useContentMode(PageContent, '[data-name="ui-page-content
   <main
     ref="UiPage"
     data-name="ui-page-wrapper"
-    class="ui-page h-full flex flex-col"
+    :class="[
+      'ui-page h-full flex flex-col [--ui-page-padding:var(--spacing-space-4)] md:[--ui-page-padding:var(--spacing-space-6)]',
+      pageInlineClass,
+    ]"
   >
     <section
       v-if="bannerSlot"
@@ -211,13 +354,21 @@ const { contentMode } = useContentMode(PageContent, '[data-name="ui-page-content
       </section>
 
       <section
-        ref="PageContent"
+        v-if="$slots.pageSummary"
+        data-name="pageSummary"
+        class="px-4 pb-(--ui-page-padding) md:pl-0 md:pr-8"
+      >
+        <slot name="pageSummary" />
+      </section>
+
+      <section
         data-name="pageContent"
         :class="[
-          'page-content flex-1 w-full grid has-[>:nth-child(2)]:lg:grid-cols-[1fr_2fr] lg:gap-x-8 min-h-0',
-          scrollClass,
+          'page-content flex-1 w-full grid min-h-0',
+          frameGutterClass,
+          pageColumnsClass,
+          pageContentScrollClass,
         ]"
-        :data-colors-semantic="contentMode"
       >
         <aside
           v-if="leftSlot && displayLeftSlot"
@@ -227,23 +378,30 @@ const { contentMode } = useContentMode(PageContent, '[data-name="ui-page-content
           <slot name="leftSlot" />
         </aside>
 
+        <!-- No overflow-hidden here: the card handles its own content
+             clipping via scrollClass, and clipping this wrapper would eat
+             the card's elevation shadow on every side but the top. -->
         <div
-          class="min-w-0 overflow-hidden rounded-tl-xl"
+          ref="PageContent"
+          data-name="ui-page-content"
+          :class="['min-w-0', cardRadiusClass]"
           :style="headroomGapStyle"
+          :data-colors-semantic="contentMode"
         >
           <section
             :class="[
-              'content min-w-0 h-full bg-surface-neutral-bg-main grid shadow-shadows-drop-shadow-2xl rounded-tl-xl',
+              'content min-w-0 h-full grid [view-transition-name:ui-page-card]',
+              cardChromeClass,
+              cardRadiusClass,
               scrollClass,
               cardRowsClass,
-              props.pageContentClasses,
             ]"
             data-name="ui-shell-content"
           >
             <section
               v-if="headerSlot"
               data-name="header"
-              class="content-header p-4 sm:p-6"
+              :class="['content-header', insets.header, headerBottomPaddingClass]"
             >
               <slot name="header" />
             </section>
@@ -252,10 +410,10 @@ const { contentMode } = useContentMode(PageContent, '[data-name="ui-page-content
               data-name="main-content"
               :class="[
                 'route-content w-full min-w-0 flex flex-col',
+                contentPaddingClass,
                 // Let the row shrink so an editor's own overflow containers
-                // resolve against a real height. Scoped to `app` so the 15
-                // existing document pages keep their current growth behaviour.
-                isApp ? 'min-h-0' : '',
+                // resolve against a real height. Document pages keep growing.
+                fillsCard ? 'min-h-0' : '',
               ]"
             >
               <slot>

package/src/components/UiPagination/UiPagination.vue

@@ -0,0 +1,99 @@
+<script setup lang="ts">
+import { computed } from 'vue'
+import { PaginationEllipsis, PaginationList, PaginationListItem, PaginationNext, PaginationPrev, PaginationRoot } from 'reka-ui'
+import { PAGINATION_ACTIVE_CLASSES, PAGINATION_IDLE_CLASSES, PAGINATION_RAIL_CLASSES } from './types'
+import type { UiPaginationColor } from './types'
+
+interface UiPaginationProps {
+  /** Controlled current page. Bind with `v-model:page`. */
+  page?: number
+  /** Initial page when uncontrolled. */
+  defaultPage?: number
+  /** Number of items per page. */
+  itemsPerPage?: number
+  /** Total number of items across all pages. */
+  total: number
+  /** Number of sibling pages shown around the current page. */
+  siblingCount?: number
+  disabled?: boolean
+  /** Always show the first and last page, with an ellipsis in between when needed. */
+  showEdges?: boolean
+  color?: UiPaginationColor
+  previousLabel?: string
+  nextLabel?: string
+}
+
+const props = withDefaults(defineProps<UiPaginationProps>(), {
+  page: undefined,
+  defaultPage: 1,
+  itemsPerPage: 10,
+  siblingCount: 1,
+  disabled: false,
+  showEdges: true,
+  color: 'neutral',
+  previousLabel: 'Previous page',
+  nextLabel: 'Next page',
+})
+
+defineEmits<{
+  'update:page': [value: number]
+}>()
+
+const idleClasses = computed(() => PAGINATION_IDLE_CLASSES[props.color])
+const activeClasses = computed(() => PAGINATION_ACTIVE_CLASSES[props.color])
+const railClasses = computed(() => PAGINATION_RAIL_CLASSES[props.color])
+</script>
+
+<template>
+  <PaginationRoot
+    :page="page"
+    :default-page="defaultPage"
+    :items-per-page="itemsPerPage"
+    :total="total"
+    :sibling-count="siblingCount"
+    :disabled="disabled"
+    :show-edges="showEdges"
+    class="inline-flex items-center gap-2"
+    @update:page="$emit('update:page', $event)"
+  >
+    <PaginationPrev
+      class="flex h-10 shrink-0 items-center justify-center rounded-button-lg px-2.5 outline-none transition-colors focus-visible:focus-ring disabled:pointer-events-none disabled:opacity-50"
+      :class="idleClasses"
+      :aria-label="previousLabel"
+    >
+      <span class="i-ph-caret-left size-4" />
+    </PaginationPrev>
+
+    <PaginationList
+      v-slot="{ items }"
+      class="flex h-10 shrink-0 items-center gap-1 rounded-button-lg p-0.5"
+      :class="railClasses"
+    >
+      <template
+        v-for="(item, index) in items"
+        :key="item.type === 'page' ? `page-${item.value}` : `ellipsis-${index}`"
+      >
+        <PaginationListItem
+          v-if="item.type === 'page'"
+          :value="item.value"
+          class="flex h-full items-center justify-center rounded-[calc(var(--radius-button-lg)_-_2px)] px-3 text-action-button-md outline-none transition-colors focus-visible:focus-ring"
+          :class="[idleClasses, activeClasses]"
+        >
+          {{ item.value }}
+        </PaginationListItem>
+        <PaginationEllipsis
+          v-else
+          class="flex h-full items-center justify-center px-3 text-action-button-md text-actions-neutral-idle"
+        />
+      </template>
+    </PaginationList>
+
+    <PaginationNext
+      class="flex h-10 shrink-0 items-center justify-center rounded-button-lg px-2.5 outline-none transition-colors focus-visible:focus-ring disabled:pointer-events-none disabled:opacity-50"
+      :class="idleClasses"
+      :aria-label="nextLabel"
+    >
+      <span class="i-ph-caret-right size-4" />
+    </PaginationNext>
+  </PaginationRoot>
+</template>

package/src/components/UiPagination/index.ts

@@ -0,0 +1,2 @@
+export { default as UiPagination } from './UiPagination.vue'
+export type { UiPaginationColor } from './types'

package/src/components/UiPagination/types.ts

@@ -0,0 +1,28 @@
+export type UiPaginationColor = 'neutral' | 'neutral-invert' | 'primary' | 'success' | 'warning' | 'error'
+
+export const PAGINATION_IDLE_CLASSES: Record<UiPaginationColor, string> = {
+  'neutral': 'text-actions-neutral-idle hover:bg-actions-neutral-hover-overlay',
+  'neutral-invert': 'text-actions-neutral-invert-idle-alpha-strong hover:bg-actions-neutral-invert-hover-overlay hover:text-actions-neutral-invert-idle',
+  'primary': 'text-actions-primary-idle-alpha-strong hover:bg-actions-primary-hover-overlay hover:text-actions-primary-idle',
+  'success': 'text-actions-success-idle-alpha-strong hover:bg-actions-success-hover-overlay hover:text-actions-success-idle',
+  'warning': 'text-actions-warning-idle-alpha-strong hover:bg-actions-warning-hover-overlay hover:text-actions-warning-idle',
+  'error': 'text-actions-danger-idle-alpha-strong hover:bg-actions-danger-hover-overlay hover:text-actions-danger-idle',
+}
+
+export const PAGINATION_ACTIVE_CLASSES: Record<UiPaginationColor, string> = {
+  'neutral': 'data-[selected=true]:bg-actions-neutral-idle data-[selected=true]:text-actions-neutral-invert-idle data-[selected=true]:hover:bg-actions-neutral-idle',
+  'neutral-invert': 'data-[selected=true]:bg-actions-neutral-invert-idle data-[selected=true]:text-actions-neutral-idle data-[selected=true]:hover:bg-actions-neutral-invert-idle',
+  'primary': 'data-[selected=true]:bg-actions-primary-idle data-[selected=true]:text-actions-neutral-invert-idle data-[selected=true]:hover:bg-actions-primary-idle',
+  'success': 'data-[selected=true]:bg-actions-success-idle data-[selected=true]:text-actions-neutral-invert-idle data-[selected=true]:hover:bg-actions-success-idle',
+  'warning': 'data-[selected=true]:bg-actions-warning-idle data-[selected=true]:text-actions-neutral-invert-idle data-[selected=true]:hover:bg-actions-warning-idle',
+  'error': 'data-[selected=true]:bg-actions-danger-idle data-[selected=true]:text-actions-neutral-invert-idle data-[selected=true]:hover:bg-actions-danger-idle',
+}
+
+export const PAGINATION_RAIL_CLASSES: Record<UiPaginationColor, string> = {
+  'neutral': 'bg-actions-neutral-idle-alpha-light',
+  'neutral-invert': 'bg-actions-neutral-invert-idle-alpha-light',
+  'primary': 'bg-actions-primary-idle-alpha-light',
+  'success': 'bg-actions-success-idle-alpha-light',
+  'warning': 'bg-actions-warning-idle-alpha-light',
+  'error': 'bg-actions-danger-idle-alpha-light',
+}

package/src/components/UiPane/UiPane.vue

@@ -0,0 +1,20 @@
+<script setup lang="ts">
+import type { DialogRootEmits, DialogRootProps } from 'reka-ui'
+import { DialogRoot, useForwardPropsEmits } from 'reka-ui'
+
+// A pane floats above the interface without an overlay, so it is non-modal by default.
+const props = withDefaults(defineProps<DialogRootProps>(), {
+  open: undefined,
+  defaultOpen: false,
+  modal: false,
+})
+const emits = defineEmits<DialogRootEmits>()
+
+const forwarded = useForwardPropsEmits(props, emits)
+</script>
+
+<template>
+  <DialogRoot v-bind="{ ...forwarded, ...$attrs }">
+    <slot />
+  </DialogRoot>
+</template>