@inglorious/ui 6.0.0 → 7.0.0

package/src/data-display/before-after/template.js

@@ -0,0 +1,225 @@
+/**
+ * @typedef {import('../../../types/data-display/before-after.js').BeforeAfterProps} BeforeAfterProps
+ * @typedef {import('@inglorious/web').TemplateResult} TemplateResult
+ */
+
+import { clamp } from "@inglorious/utils/math/numbers.js"
+import { html } from "@inglorious/web"
+import { classMap } from "@inglorious/web/directives/class-map"
+
+import {
+  DEFAULT_POSITION,
+  DEFAULT_STEP,
+  MAX_POSITION,
+  MIN_POSITION,
+} from "./helpers.js"
+
+const PRIMARY_BUTTON = 1
+
+export const BeforeAfter = {
+  /**
+   * Main entrypoint for the before/after template. It delegates to the base renderer so overrides can still reuse it.
+   * Before/after overlays two images and reveals the top one with a draggable divider.
+   * @param {BeforeAfterProps} props The before/after props.
+   * @returns {TemplateResult} The rendered control.
+   */
+  render(props) {
+    return this.renderBeforeAfter(props)
+  },
+
+  /**
+   * Renders the container and wires the pointer and keyboard interactions.
+   * This is the canonical renderer that custom `render()` overrides should call.
+   * @param {BeforeAfterProps} props The before/after props.
+   * @returns {TemplateResult} The rendered control.
+   */
+  renderBeforeAfter(props) {
+    const {
+      label,
+      position = DEFAULT_POSITION,
+      isDisabled = false,
+      isFullWidth = false,
+    } = props
+
+    const classes = {
+      "iw-before-after": true,
+      "iw-before-after-full-width": isFullWidth,
+      "iw-before-after-disabled": isDisabled,
+    }
+
+    return html`<div
+      class=${classMap(classes)}
+      style="--iw-before-after-position: ${position}%;"
+      role="slider"
+      tabindex=${isDisabled ? -1 : 0}
+      aria-label=${label || "Before and after comparison"}
+      aria-orientation="horizontal"
+      aria-valuemin=${MIN_POSITION}
+      aria-valuemax=${MAX_POSITION}
+      aria-valuenow=${Math.round(position)}
+      aria-disabled=${isDisabled}
+      @pointerdown=${handlePointerDown(props)}
+      @pointermove=${handlePointerMove(props)}
+      @pointerup=${handlePointerUp}
+      @pointercancel=${handlePointerUp}
+      @keydown=${handleKeyDown(props)}
+    >
+      ${this.renderBefore?.(props)} ${this.renderAfter?.(props)}
+      ${this.renderDivider?.(props)}
+    </div>`
+  },
+
+  /**
+   * Renders the bottom layer, fully visible underneath the clipped one.
+   * It also gives the control its intrinsic size.
+   * @param {BeforeAfterProps} props The before/after props.
+   * @returns {TemplateResult} The rendered layer.
+   */
+  renderBefore(props) {
+    return html`<div class="iw-before-after-item iw-before-after-before">
+      <img
+        class="iw-before-after-image"
+        src=${props.before?.src ?? ""}
+        alt=${props.before?.alt ?? ""}
+        draggable="false"
+      />
+    </div>`
+  },
+
+  /**
+   * Renders the top layer, clipped to the current divider position through CSS.
+   * @param {BeforeAfterProps} props The before/after props.
+   * @returns {TemplateResult} The rendered layer.
+   */
+  renderAfter(props) {
+    return html`<div class="iw-before-after-item iw-before-after-after">
+      <img
+        class="iw-before-after-image"
+        src=${props.after?.src ?? ""}
+        alt=${props.after?.alt ?? ""}
+        draggable="false"
+      />
+    </div>`
+  },
+
+  /**
+   * Renders the vertical bar sitting on the seam between the two layers.
+   * Override this to change the separator, or drop the handle entirely.
+   * @param {BeforeAfterProps} props The before/after props.
+   * @returns {TemplateResult} The rendered divider.
+   */
+  renderDivider(props) {
+    return html`<div class="iw-before-after-divider" aria-hidden="true">
+      ${this.renderHandle?.(props)}
+    </div>`
+  },
+
+  /**
+   * Renders the grip shown at the centre of the divider.
+   * Override this to supply a custom handle.
+   * @returns {TemplateResult} The rendered handle.
+   */
+  renderHandle() {
+    return html`<div class="iw-before-after-handle"></div>`
+  },
+}
+
+/**
+ * Start dragging: capture the pointer so moves keep tracking outside the box.
+ * @param {BeforeAfterProps} props
+ * @returns {(event: PointerEvent) => void}
+ */
+function handlePointerDown(props) {
+  return (event) => {
+    if (props.isDisabled) return
+
+    event.currentTarget.setPointerCapture?.(event.pointerId)
+    move(props, event)
+  }
+}
+
+/**
+ * Track the divider while the primary button or contact is held down.
+ * @param {BeforeAfterProps} props
+ * @returns {(event: PointerEvent) => void}
+ */
+function handlePointerMove(props) {
+  return (event) => {
+    if (props.isDisabled) return
+    if (!(event.buttons & PRIMARY_BUTTON)) return
+
+    move(props, event)
+  }
+}
+
+/**
+ * Stop dragging.
+ * @param {PointerEvent} event
+ */
+function handlePointerUp(event) {
+  event.currentTarget.releasePointerCapture?.(event.pointerId)
+}
+
+/**
+ * Move the divider with the arrow keys, or jump to either edge.
+ * @param {BeforeAfterProps} props
+ * @returns {(event: KeyboardEvent) => void}
+ */
+function handleKeyDown(props) {
+  return (event) => {
+    if (props.isDisabled) return
+
+    const position = props.position ?? DEFAULT_POSITION
+    const step = props.step ?? DEFAULT_STEP
+
+    let next
+    switch (event.key) {
+      case "ArrowLeft":
+      case "ArrowDown":
+        next = position - step
+        break
+      case "ArrowRight":
+      case "ArrowUp":
+        next = position + step
+        break
+      case "Home":
+        next = MIN_POSITION
+        break
+      case "End":
+        next = MAX_POSITION
+        break
+      default:
+        return
+    }
+
+    event.preventDefault()
+    props.onPositionChange?.(clamp(next, MIN_POSITION, MAX_POSITION))
+  }
+}
+
+/**
+ * Report the divider position under the pointer.
+ * @param {BeforeAfterProps} props
+ * @param {PointerEvent} event
+ */
+function move(props, event) {
+  const position = positionFromEvent(event)
+  if (position != null) props.onPositionChange?.(position)
+}
+
+/**
+ * Convert a pointer event into a divider position (0-100) relative to the
+ * element the listener is attached to. Null when it has no measurable width.
+ * @param {PointerEvent} event
+ * @returns {number | null}
+ */
+function positionFromEvent(event) {
+  const rect = event.currentTarget.getBoundingClientRect()
+  if (!rect.width) return null
+
+  return clamp(
+    ((event.clientX - rect.left) / rect.width) * 100,
+    MIN_POSITION,
+    MAX_POSITION,
+  )
+}

package/src/data-display/carousel/carousel.stories.js

@@ -0,0 +1,166 @@
+import { html } from "@inglorious/web"
+
+import {
+  createEntityRender,
+  notifyActionArgType,
+} from "../../stories/notifyStory.js"
+import { Carousel } from "./index.js"
+
+const COLORS = ["#22d3ee", "#4f46e5", "#f59e0b", "#10b981", "#ef4444"]
+
+const slide = (index) =>
+  html`<div
+    style="display:grid;place-items:center;height:14rem;border-radius:0.5rem;
+           background:${COLORS[index]};color:#fff;font:700 2rem sans-serif;"
+  >
+    ${index + 1}
+  </div>`
+
+const items = COLORS.map((color, index) => slide(index))
+
+export default {
+  title: "Data Display/Carousel",
+  tags: ["autodocs"],
+  render: createEntityRender({ Carousel }),
+  argTypes: {
+    ...notifyActionArgType,
+    label: { control: "text", description: "Accessible label." },
+    page: {
+      control: "number",
+      description: "Index of the item the viewport settled on.",
+    },
+    axis: {
+      control: "inline-radio",
+      options: ["x", "y"],
+      description: "Scroll direction.",
+    },
+    gap: {
+      control: "select",
+      options: ["none", "sm", "md", "lg", "xl"],
+      description: "Spacing between items.",
+    },
+    align: {
+      control: "select",
+      options: ["stretch", "start", "center", "end"],
+      description: "Off-axis alignment of items.",
+    },
+    arrowPlacement: {
+      control: "inline-radio",
+      options: ["inside", "outside"],
+      description: "Float the arrows over the slides, or sit them beside.",
+    },
+    arrowVariant: {
+      control: "select",
+      options: ["default", "outline", "ghost"],
+      description: "Button variant used for the arrows.",
+    },
+    arrowColor: {
+      control: "select",
+      options: ["primary", "secondary", "success", "warning", "error", "info"],
+      description: "Button color used for the arrows.",
+    },
+    isInfinite: {
+      control: "boolean",
+      description: "Wrap past the ends by rotating the items.",
+    },
+    hasArrows: {
+      control: "boolean",
+      description: "Show previous/next arrows.",
+    },
+    hasIndicators: { control: "boolean", description: "Show pagination dots." },
+    isFullWidth: {
+      control: "boolean",
+      description: "Expand to container width.",
+    },
+  },
+  parameters: {
+    docs: {
+      description: {
+        component:
+          "Carousel built on CSS scroll snapping: swiping, momentum and snapping come from the browser, while the entity holds the current page. Drag, use the arrows or dots, or focus the viewport and use the arrow keys / Home / End.",
+      },
+    },
+  },
+}
+
+export const Default = {}
+Default.args = {
+  id: "carousel",
+  type: "Carousel",
+  label: "Example carousel",
+  items,
+  page: 0,
+  axis: "x",
+  gap: "md",
+  align: "stretch",
+  arrowPlacement: "inside",
+  arrowVariant: "default",
+  isInfinite: true,
+  hasArrows: true,
+  hasIndicators: true,
+  isFullWidth: true,
+}
+
+/** Arrows beside the scrolling area, as most carousels show them. */
+export const ArrowsOutside = {}
+ArrowsOutside.args = {
+  ...Default.args,
+  id: "carousel-arrows-outside",
+  arrowPlacement: "outside",
+  arrowVariant: "ghost",
+}
+
+/** Wraps past the ends: after 5 it continues to 1, rather than rewinding. */
+export const Infinite = {}
+Infinite.args = {
+  ...Default.args,
+  id: "carousel-infinite",
+  isInfinite: true,
+}
+
+export const StartOnThirdSlide = {}
+StartOnThirdSlide.args = {
+  ...Default.args,
+  id: "carousel-third",
+  page: 2,
+}
+
+/**
+ * Vertical carousels need a height to scroll within: set
+ * `--iw-carousel-viewport-size` (it defaults to `20rem`).
+ */
+export const Vertical = {}
+Vertical.args = {
+  ...Default.args,
+  id: "carousel-vertical",
+  axis: "y",
+}
+Vertical.decorators = [
+  (story) =>
+    html`<div style="--iw-carousel-viewport-size: 14rem">${story()}</div>`,
+]
+
+export const Bare = {}
+Bare.args = {
+  ...Default.args,
+  id: "carousel-bare",
+  hasArrows: false,
+  hasIndicators: false,
+}
+
+/**
+ * Several items at once, by overriding `--iw-carousel-item-size`.
+ * Trailing items share the final scroll position, so the last pages settle
+ * together — one item per view is the exact case.
+ */
+export const ManyPerView = {}
+ManyPerView.args = {
+  ...Default.args,
+  id: "carousel-many",
+  // The infinite treadmill keeps one slide at its centre, so it is not a good
+  // fit when several slides are intentionally visible at once.
+  isInfinite: false,
+}
+ManyPerView.decorators = [
+  (story) => html`<div style="--iw-carousel-item-size: 14rem">${story()}</div>`,
+]

package/src/data-display/carousel/handlers.js

@@ -0,0 +1,78 @@
+/**
+ * @typedef {import('../../../types/data-display/carousel.js').CarouselProps} CarouselEntity
+ */
+
+import {
+  clampPage,
+  DEFAULT_ALIGN,
+  DEFAULT_ARROW_PLACEMENT,
+  DEFAULT_ARROW_VARIANT,
+  DEFAULT_AXIS,
+  DEFAULT_GAP,
+  FIRST_PAGE,
+  NO_ROTATION,
+  normalizeRotation,
+} from "./helpers.js"
+
+const ENOUGH_TO_WRAP = 1
+
+/**
+ * Initialize missing carousel state defaults.
+ * The only persistent piece of state is `page`: the index of the item the
+ * viewport has settled on. Everything else is configuration.
+ * @param {CarouselEntity} entity
+ */
+export function create(entity) {
+  entity.items ??= []
+  entity.page ??= FIRST_PAGE
+  entity.rotation ??= NO_ROTATION
+
+  entity.isInfinite ??= false
+  entity.axis ??= DEFAULT_AXIS
+  entity.gap ??= DEFAULT_GAP
+  entity.align ??= DEFAULT_ALIGN
+
+  entity.arrowPlacement ??= DEFAULT_ARROW_PLACEMENT
+  entity.arrowVariant ??= DEFAULT_ARROW_VARIANT
+
+  entity.label ??= ""
+  entity.hasArrows ??= true
+  entity.hasIndicators ??= true
+  entity.isFullWidth ??= false
+
+  // An infinite carousel keeps the current item in the middle slot, so the
+  // starting item is placed there by rotating the strip up front.
+  if (entity.isInfinite && entity.items.length > ENOUGH_TO_WRAP) {
+    const home = Math.floor(entity.items.length / 2)
+    entity.rotation = normalizeRotation(entity.page - home, entity.items.length)
+    entity.page = home
+  }
+}
+
+/**
+ * Settle on another page, clamped to the available items.
+ * @param {CarouselEntity} entity
+ * @param {number} page
+ */
+export function pageChange(entity, page) {
+  const value = Number(page)
+  if (Number.isNaN(value)) return
+
+  entity.page = clampPage(value, entity.items)
+}
+
+/**
+ * Rotate the items by `step` (wrapping), which is how an infinite carousel
+ * continues forward past the end instead of rewinding to the start.
+ * @param {CarouselEntity} entity
+ * @param {number} step
+ */
+export function rotate(entity, step) {
+  const value = Number(step)
+  if (Number.isNaN(value)) return
+
+  entity.rotation = normalizeRotation(
+    (entity.rotation ?? NO_ROTATION) + value,
+    entity.items?.length ?? 0,
+  )
+}

package/src/data-display/carousel/helpers.js

@@ -0,0 +1,54 @@
+import { clamp } from "@inglorious/utils/math/numbers.js"
+
+export const DEFAULT_AXIS = "x"
+export const VERTICAL_AXIS = "y"
+export const DEFAULT_GAP = "none"
+export const DEFAULT_ALIGN = "stretch"
+export const DEFAULT_ARROW_PLACEMENT = "inside"
+export const DEFAULT_ARROW_VARIANT = "default"
+export const FIRST_PAGE = 0
+export const NO_ROTATION = 0
+
+/**
+ * Bring a rotation into the `0 .. len - 1` range, wrapping negatives.
+ * @param {number} rotation
+ * @param {number} length
+ * @returns {number}
+ */
+export function normalizeRotation(rotation, length) {
+  if (length <= 0) return NO_ROTATION
+  return ((rotation % length) + length) % length
+}
+
+/**
+ * Rotate items so that `items[rotation]` becomes the first one — this is how an
+ * infinite carousel turns `[1, 2, 3, 4, 5]` into `[2, 3, 4, 5, 1]` instead of
+ * rewinding all the way back to the start.
+ * @param {unknown[]} [items]
+ * @param {number} [rotation]
+ * @returns {unknown[]}
+ */
+export function rotateItems(items = [], rotation = NO_ROTATION) {
+  if (!items.length) return items
+  const at = normalizeRotation(rotation, items.length)
+  return items.slice(at).concat(items.slice(0, at))
+}
+
+/**
+ * Get the index of the last available page.
+ * @param {unknown[]} [items]
+ * @returns {number}
+ */
+export function getLastPage(items = []) {
+  return Math.max(FIRST_PAGE, items.length - 1)
+}
+
+/**
+ * Keep a page index within the available pages.
+ * @param {number} page
+ * @param {unknown[]} [items]
+ * @returns {number}
+ */
+export function clampPage(page, items) {
+  return clamp(page, FIRST_PAGE, getLastPage(items))
+}

package/src/data-display/carousel/index.js

@@ -0,0 +1,17 @@
+import * as handlers from "./handlers.js"
+import { Carousel as renderers } from "./template.js"
+
+export const Carousel = {
+  ...handlers,
+  ...renderers,
+  render(entity, api) {
+    const id = entity.id
+    const props = {
+      ...entity,
+      onPageChange: (page) => api.notify(`#${id}:pageChange`, page),
+      onRotate: (step) => api.notify(`#${id}:rotate`, step),
+    }
+
+    return this.renderCarousel(props)
+  },
+}