@inglorious/ui 5.0.0 → 6.1.0

package/src/examples/dashboard/primitive-content.js

@@ -1,4 +1,5 @@
-import { html } from "@inglorious/web"
+import { createStore } from "@inglorious/store"
+import { html, mount } from "@inglorious/web"
 
 import { Button } from "../../controls/button/index.js"
 import { ButtonGroup } from "../../controls/button-group/index.js"
@@ -14,6 +15,8 @@ import { Slider } from "../../controls/slider/index.js"
 import { Switch } from "../../controls/switch/index.js"
 import { Avatar } from "../../data-display/avatar/index.js"
 import { Badge } from "../../data-display/badge/index.js"
+import { BeforeAfter } from "../../data-display/before-after/index.js"
+import { Carousel } from "../../data-display/carousel/index.js"
 import { Chip } from "../../data-display/chip/index.js"
 import { DataGrid } from "../../data-display/data-grid/index.js"
 import { Divider } from "../../data-display/divider/index.js"
@@ -45,6 +48,7 @@ import { Accordion } from "../../surfaces/accordion/index.js"
 import { AppBar } from "../../surfaces/app-bar/index.js"
 import { Card } from "../../surfaces/card/index.js"
 import { Paper } from "../../surfaces/paper/index.js"
+import { beforeAfterImages } from "./before-after-data.js"
 
 const categoryMeta = {
   layout: {
@@ -102,6 +106,48 @@ const previewRow = (children) =>
 const previewColumn = (children) =>
   html`<div class="iw-primitive-preview-column">${children}</div>`
 
+const livePreviews = new Map()
+
+/**
+ * Entity-driven primitives render their controls from state, so a preview
+ * without a store freezes: a carousel arrow would recompute from the same page
+ * forever, and a dragged divider would never move. Give each one its own store,
+ * created once and reused on every re-render so the preview keeps its state.
+ * @param {Object.<string, any>} types
+ * @param {Object.<string, any>} entity
+ * @returns {HTMLElement}
+ */
+function livePreview(types, entity) {
+  if (!livePreviews.has(entity.id)) {
+    const container = document.createElement("div")
+    // The mount needs an element, but it must not become a box of its own:
+    // as a flex item it would shrink and take the primitive down with it.
+    container.style.display = "contents"
+
+    const store = createStore({ types, entities: { [entity.id]: entity } })
+    mount(store, (api) => api.render(entity.id), container)
+    livePreviews.set(entity.id, container)
+  }
+
+  return livePreviews.get(entity.id)
+}
+
+const carouselSlides = [
+  "#22d3ee",
+  "#4f46e5",
+  "#f59e0b",
+  "#10b981",
+  "#ef4444",
+].map(
+  (color, index) =>
+    html`<div
+      style="display:grid;place-items:center;height:14rem;border-radius:0.5rem;
+             background:${color};color:#fff;font:700 2rem sans-serif;"
+    >
+      ${index + 1}
+    </div>`,
+)
+
 const primitiveDetailsByPath = {
   "/layout/container": {
     summary: "Constrains content width and applies consistent gutters.",
@@ -195,6 +241,38 @@ Grid.render({
         }),
     },
   },
+  "/data-display/carousel": {
+    summary: "Scroll-snapping carousel with arrows and pagination dots.",
+    description:
+      "Carousel lays items out in a scroll-snapping viewport: swiping, momentum and snapping come from the browser, while the current page is the only piece of entity state. Arrows and indicators are overridable sub-renders.",
+    useCases: ["Image galleries", "Feature tours", "Onboarding slides"],
+    example: {
+      code: `import { Carousel } from "@inglorious/ui/carousel"
+
+Carousel.render({
+  id: "demo",
+  label: "Example carousel",
+  items: [slideOne, slideTwo, slideThree],
+  page: 0,
+  gap: "md",
+  isFullWidth: true
+})`,
+      preview: () =>
+        livePreview(
+          { Carousel },
+          {
+            id: "carousel",
+            type: "Carousel",
+            label: "Example carousel",
+            items: carouselSlides,
+            page: 0,
+            gap: "md",
+            isInfinite: true,
+            isFullWidth: true,
+          },
+        ),
+    },
+  },
   "/controls/button": {
     summary: "Action trigger with variants, colors, and shapes.",
     description:
@@ -280,6 +358,36 @@ Checkbox.render({
         ]),
     },
   },
+  "/data-display/before-after": {
+    name: "Before / After",
+    summary: "Drag-to-compare slider for two overlaid images.",
+    description:
+      "Before/After overlays two images and reveals the top one with a draggable divider. The reveal is pure CSS (clip-path) and the divider position is the only piece of entity state; the divider and handle follow the active theme and color mode.",
+    useCases: ["Image comparisons", "Before/after edits", "Visual diffs"],
+    example: {
+      code: `import { BeforeAfter } from "@inglorious/ui/before-after"
+
+BeforeAfter.render({
+  id: "demo",
+  before: { src: "before.jpg", alt: "Before" },
+  after: { src: "after.jpg", alt: "After" },
+  position: 50,
+  isFullWidth: true
+})`,
+      preview: () =>
+        livePreview(
+          { BeforeAfter },
+          {
+            id: "beforeAfter",
+            type: "BeforeAfter",
+            before: beforeAfterImages.before,
+            after: beforeAfterImages.after,
+            position: 50,
+            isFullWidth: true,
+          },
+        ),
+    },
+  },
   "/controls/combobox": {
     summary: "Searchable dropdown with multi-select and tag support.",
     description:
@@ -304,21 +412,26 @@ Combobox.render({
   selectedValue: ["inglorious"]
 })`,
       preview: () =>
-        Combobox.render({
-          label: "Frameworks",
-          placeholder: "Select frameworks...",
-          isMulti: true,
-          isSearchable: true,
-          isClearable: true,
-          options: [
-            { label: "React", value: "react" },
-            { label: "Angular", value: "angular" },
-            { label: "Vue", value: "vue" },
-            { label: "Svelte", value: "svelte" },
-            { label: "Inglorious", value: "inglorious" },
-          ],
-          selectedValue: ["inglorious"],
-        }),
+        livePreview(
+          { Combobox },
+          {
+            id: "combobox",
+            type: "Combobox",
+            label: "Frameworks",
+            placeholder: "Select frameworks...",
+            isMulti: true,
+            isSearchable: true,
+            isClearable: true,
+            options: [
+              { label: "React", value: "react" },
+              { label: "Angular", value: "angular" },
+              { label: "Vue", value: "vue" },
+              { label: "Svelte", value: "svelte" },
+              { label: "Inglorious", value: "inglorious" },
+            ],
+            selectedValue: ["inglorious"],
+          },
+        ),
     },
   },
   "/controls/fab": {
@@ -590,23 +703,28 @@ DataGrid.render({
   pagination: { page: 0, pageSize: 3, pageSizes: [3, 6] }
 })`,
       preview: () =>
-        DataGrid.render({
-          rowId: "id",
-          columns: [
-            { id: "id", title: "ID", type: "number", isSortable: true },
-            { id: "name", title: "Name" },
-            { id: "status", title: "Status" },
-          ],
-          rows: [
-            { id: 1, name: "Alpha", status: "Active" },
-            { id: 2, name: "Beta", status: "Paused" },
-            { id: 3, name: "Gamma", status: "Active" },
-          ],
-          filters: {},
-          sorts: [],
-          selection: [],
-          pagination: { page: 0, pageSize: 3, pageSizes: [3, 6] },
-        }),
+        livePreview(
+          { DataGrid },
+          {
+            id: "dataGrid",
+            type: "DataGrid",
+            rowId: "id",
+            columns: [
+              { id: "id", title: "ID", type: "number", isSortable: true },
+              { id: "name", title: "Name" },
+              { id: "status", title: "Status" },
+            ],
+            rows: [
+              { id: 1, name: "Alpha", status: "Active" },
+              { id: 2, name: "Beta", status: "Paused" },
+              { id: 3, name: "Gamma", status: "Active" },
+            ],
+            filters: {},
+            sorts: [],
+            selection: [],
+            pagination: { page: 0, pageSize: 3, pageSizes: [3, 6] },
+          },
+        ),
     },
   },
   "/data-display/divider": {

package/src/index.js

@@ -11,6 +11,8 @@ export { Slider } from "./controls/slider/index.js"
 export { Switch } from "./controls/switch/index.js"
 export { Avatar } from "./data-display/avatar/index.js"
 export { Badge } from "./data-display/badge/index.js"
+export { BeforeAfter } from "./data-display/before-after/index.js"
+export { Carousel } from "./data-display/carousel/index.js"
 export { Chip } from "./data-display/chip/index.js"
 export { DataGrid } from "./data-display/data-grid/index.js"
 export { Divider } from "./data-display/divider/index.js"

package/src/layout/flex/flex.stories.js

@@ -38,6 +38,12 @@ export default {
       options: ["none", "sm", "md", "lg", "xl"],
       description: "Inner padding for the flex container.",
     },
+    overflow: {
+      control: "select",
+      options: ["visible", "hidden", "clip", "scroll", "auto"],
+      description:
+        "Overflow behavior. Scrollable values also release flex minimum dimensions.",
+    },
     element: {
       control: "select",
       options: [
@@ -84,6 +90,7 @@ Default.args = {
   align: "stretch",
   gap: "md",
   padding: "none",
+  overflow: "visible",
   element: "div",
   isInline: false,
   isFullWidth: false,
@@ -119,3 +126,45 @@ Wrapped.args = {
     html`<div>Six</div>`,
   ],
 }
+
+export const ScrollableContent = {}
+ScrollableContent.args = {
+  direction: "column",
+  element: "section",
+  overflow: "hidden",
+  className: "iw-flex-scrollable-story",
+  style: { height: "24rem", border: "1px solid var(--iw-color-border)" },
+  children: [
+    Flex.render({
+      element: "header",
+      padding: "md",
+      style: {
+        flex: "0 0 3.5rem",
+        background: "var(--iw-color-surface)",
+      },
+      children: ["Fixed header"],
+    }),
+    Flex.render({
+      element: "main",
+      direction: "column",
+      overflow: "auto",
+      padding: "md",
+      style: { flex: "1 1 0" },
+      children: [
+        html`<div style="min-height: 48rem">
+          This content is intentionally taller than the available space. The
+          header and footer stay visible while this main area scrolls.
+        </div>`,
+      ],
+    }),
+    Flex.render({
+      element: "footer",
+      padding: "md",
+      style: {
+        flex: "0 0 3.5rem",
+        background: "var(--iw-color-surface)",
+      },
+      children: ["Fixed footer"],
+    }),
+  ],
+}

package/src/layout/flex/style.css

@@ -120,4 +120,63 @@
   &.iw-flex-padding-xl {
     padding: var(--iw-space-8);
   }
+
+  /* A flex item needs both minimum dimensions released before either axis can
+     overflow instead of expanding its parent. */
+  &.iw-flex-overflow-auto,
+  &.iw-flex-overflow-scroll,
+  &.iw-flex-overflow-hidden,
+  &.iw-flex-overflow-clip {
+    min-width: 0;
+    min-height: 0;
+  }
+
+  &.iw-flex-overflow-auto {
+    overflow: auto;
+  }
+
+  &.iw-flex-overflow-scroll {
+    overflow: scroll;
+  }
+
+  &.iw-flex-overflow-hidden {
+    overflow: hidden;
+  }
+
+  &.iw-flex-overflow-clip {
+    overflow: clip;
+  }
+
+  &.iw-flex-overflow-visible {
+    overflow: visible;
+  }
+
+  &.iw-flex-overflow-auto,
+  &.iw-flex-overflow-scroll {
+    scrollbar-color: var(--iw-color-text-muted) var(--iw-color-surface-hover);
+    scrollbar-width: thin;
+  }
+
+  &.iw-flex-overflow-auto::-webkit-scrollbar,
+  &.iw-flex-overflow-scroll::-webkit-scrollbar {
+    width: 0.625rem;
+    height: 0.625rem;
+  }
+
+  &.iw-flex-overflow-auto::-webkit-scrollbar-track,
+  &.iw-flex-overflow-scroll::-webkit-scrollbar-track {
+    background: var(--iw-color-surface-hover);
+  }
+
+  &.iw-flex-overflow-auto::-webkit-scrollbar-thumb,
+  &.iw-flex-overflow-scroll::-webkit-scrollbar-thumb {
+    border: 0.125rem solid var(--iw-color-surface-hover);
+    border-radius: var(--iw-radius-full);
+    background: var(--iw-color-text-muted);
+  }
+
+  &.iw-flex-overflow-auto::-webkit-scrollbar-thumb:hover,
+  &.iw-flex-overflow-scroll::-webkit-scrollbar-thumb:hover {
+    background: var(--iw-color-text-secondary);
+  }
 }

package/src/layout/flex/template.js

@@ -24,6 +24,7 @@ export function render(props) {
     align = "stretch",
     gap = "none",
     padding = "none",
+    overflow = "visible",
     isInline = false,
     isFullWidth = false,
     className = "",
@@ -49,6 +50,7 @@ export function render(props) {
     [`iw-flex-align-${align}`]: true,
     [`iw-flex-gap-${gap}`]: true,
     [`iw-flex-padding-${padding}`]: true,
+    [`iw-flex-overflow-${overflow}`]: true,
     ...extraClasses,
   }
 

package/types/data-display/before-after.d.ts

@@ -0,0 +1,39 @@
+import type { TemplateResult, Api } from "@inglorious/web"
+
+export interface BeforeAfterImage {
+  src: string
+  alt?: string
+}
+
+export interface BeforeAfterProps {
+  id?: string
+  type?: string
+  label?: string
+
+  before?: BeforeAfterImage | null
+  after?: BeforeAfterImage | null
+
+  /** Divider location as a percentage (0-100). The only persistent state. */
+  position?: number
+  /** Keyboard increment, in percent, for arrow keys. */
+  step?: number
+
+  isDisabled?: boolean
+  isFullWidth?: boolean
+
+  onPositionChange?: (position: number) => void
+  [key: string]: unknown
+}
+
+export interface BeforeAfterType {
+  create(entity: BeforeAfterProps): void
+  positionChange(entity: BeforeAfterProps, position: number): void
+  render(entity: BeforeAfterProps, api: Api): TemplateResult
+  renderBeforeAfter(props: BeforeAfterProps): TemplateResult
+  renderBefore(props: BeforeAfterProps): TemplateResult
+  renderAfter(props: BeforeAfterProps): TemplateResult
+  renderDivider(props: BeforeAfterProps): TemplateResult
+  renderHandle(props: BeforeAfterProps): TemplateResult
+}
+
+export declare const BeforeAfter: BeforeAfterType

package/types/data-display/carousel.d.ts

@@ -0,0 +1,72 @@
+import type { TemplateResult, Api } from "@inglorious/web"
+
+export type CarouselAxis = "x" | "y"
+export type CarouselGap = "none" | "sm" | "md" | "lg" | "xl"
+export type CarouselAlign = "stretch" | "start" | "center" | "end"
+export type CarouselDirection = "previous" | "next"
+export type CarouselArrowPlacement = "inside" | "outside"
+export type CarouselArrowVariant = "default" | "outline" | "ghost"
+export type CarouselArrowColor =
+  | "primary"
+  | "secondary"
+  | "success"
+  | "warning"
+  | "error"
+  | "info"
+
+export interface CarouselProps {
+  id?: string
+  type?: string
+  label?: string
+
+  items?: unknown[]
+  /** Index of the item the viewport has settled on. */
+  page?: number
+  /** How many items are rotated off the front (infinite carousels only). */
+  rotation?: number
+
+  /** Wrap past the ends by rotating the items instead of stopping. */
+  isInfinite?: boolean
+
+  axis?: CarouselAxis
+  gap?: CarouselGap
+  align?: CarouselAlign
+
+  /** Whether the arrows float over the slides or sit beside them. */
+  arrowPlacement?: CarouselArrowPlacement
+  /** Button variant used for the arrows. */
+  arrowVariant?: CarouselArrowVariant
+  /** Button color used for the arrows. */
+  arrowColor?: CarouselArrowColor
+
+  hasArrows?: boolean
+  hasIndicators?: boolean
+  isFullWidth?: boolean
+
+  onPageChange?: (page: number) => void
+  [key: string]: unknown
+}
+
+export interface CarouselType {
+  create(entity: CarouselProps): void
+  indicatorSelect(
+    props: CarouselProps,
+    index: number,
+    viewport: HTMLElement | null | undefined,
+  ): void
+  pageChange(entity: CarouselProps, page: number): void
+  rotate(entity: CarouselProps, step: number): void
+
+  render(entity: CarouselProps, api: Api): TemplateResult
+  renderCarousel(props: CarouselProps): TemplateResult
+  renderViewport(props: CarouselProps): TemplateResult
+  renderItem(props: CarouselProps, item: unknown, index: number): TemplateResult
+  renderArrow(
+    props: CarouselProps,
+    direction: CarouselDirection,
+  ): TemplateResult
+  renderIndicators(props: CarouselProps): TemplateResult
+  renderIndicator(props: CarouselProps, index: number): TemplateResult
+}
+
+export declare const Carousel: CarouselType

package/types/layout/flex.d.ts

@@ -18,6 +18,7 @@ export interface FlexProps {
   align?: "stretch" | "start" | "center" | "end" | "baseline"
   gap?: "none" | "sm" | "md" | "lg" | "xl"
   padding?: "none" | "sm" | "md" | "lg" | "xl"
+  overflow?: "visible" | "hidden" | "clip" | "scroll" | "auto"
   isInline?: boolean
   isFullWidth?: boolean
   children?: Array<TemplateResult | string | number>