@inglorious/ui 5.0.0 → 6.1.0

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)
+  },
+}

package/src/data-display/carousel/style.css

@@ -0,0 +1,233 @@
+.iw-carousel {
+  --iw-carousel-arrow-size: 2.25rem;
+  --iw-carousel-arrow-bg: var(--iw-color-surface);
+  --iw-carousel-arrow-color: var(--iw-color-text);
+  --iw-carousel-arrow-inset: var(--iw-space-2);
+  --iw-carousel-arrow-chevron: 5px;
+  --iw-carousel-indicator-size: 0.5rem;
+  --iw-carousel-indicator-color: var(--iw-color-border);
+  --iw-carousel-indicator-color-current: var(--iw-color-primary);
+
+  position: relative;
+  display: inline-block;
+  max-width: 100%;
+
+  &.iw-carousel-full-width {
+    display: block;
+    width: 100%;
+  }
+
+  /* A column stage otherwise shrink-wraps to its arrows instead of the
+     available inline size. */
+  &.iw-carousel-vertical {
+    display: block;
+    width: 100%;
+  }
+
+  /* Snapping, swiping, momentum and RTL all come from the browser. */
+  .iw-carousel-viewport {
+    position: relative;
+    display: flex;
+    overflow-x: auto;
+    overflow-y: hidden;
+    scroll-snap-type: x mandatory;
+    overscroll-behavior-x: contain;
+    scrollbar-width: none;
+    outline: none;
+  }
+
+  .iw-carousel-viewport::-webkit-scrollbar {
+    display: none;
+  }
+
+  .iw-carousel-viewport:focus-visible {
+    outline: 2px solid var(--iw-color-primary);
+    outline-offset: 2px;
+  }
+
+  /* One item per view by default, so every item can reach the start of the
+     viewport and each one is exactly one page. Override
+     --iw-carousel-item-size to show several at once. */
+  .iw-carousel-item {
+    flex: 0 0 var(--iw-carousel-item-size, 100%);
+    scroll-snap-align: start;
+  }
+
+  /* Smooth scrolling would animate every drag step, so it is turned off while
+     dragging. Snapping stays on: the browser then lands on the nearest slide by
+     itself, and re-enabling it instead would snap back to the item it
+     remembered. Doubled up on the class so this outranks the reduced-motion
+     rule at the end of the file. */
+  .iw-carousel-viewport.iw-carousel-viewport-dragging {
+    scroll-behavior: auto;
+    scroll-snap-type: none;
+    cursor: grabbing;
+    user-select: none;
+  }
+
+  /* A vertical carousel has to be given a height, otherwise the viewport just
+     grows to fit every item and there is nothing left to scroll. Override
+     --iw-carousel-viewport-size to change it. */
+  &.iw-carousel-vertical .iw-carousel-viewport {
+    flex-direction: column;
+    height: var(--iw-carousel-viewport-size, 20rem);
+    overflow-x: hidden;
+    overflow-y: auto;
+    scroll-snap-type: y mandatory;
+    overscroll-behavior-y: contain;
+  }
+
+  /* Gap tokens mirror Flex. */
+  &.iw-carousel-gap-sm .iw-carousel-viewport {
+    gap: var(--iw-space-2);
+  }
+
+  &.iw-carousel-gap-md .iw-carousel-viewport {
+    gap: var(--iw-space-4);
+  }
+
+  &.iw-carousel-gap-lg .iw-carousel-viewport {
+    gap: var(--iw-space-6);
+  }
+
+  &.iw-carousel-gap-xl .iw-carousel-viewport {
+    gap: var(--iw-space-8);
+  }
+
+  /* Off-axis alignment. */
+  &.iw-carousel-align-start .iw-carousel-viewport {
+    align-items: flex-start;
+  }
+
+  &.iw-carousel-align-center .iw-carousel-viewport {
+    align-items: center;
+  }
+
+  &.iw-carousel-align-end .iw-carousel-viewport {
+    align-items: flex-end;
+  }
+
+  /* The stage holds the viewport and its arrows, so centring ignores the dots. */
+  .iw-carousel-stage {
+    position: relative;
+    display: flex;
+    align-items: center;
+    gap: var(--iw-space-2);
+  }
+
+  &.iw-carousel-vertical .iw-carousel-stage {
+    flex-direction: column;
+    align-items: stretch;
+  }
+
+  .iw-carousel-stage .iw-carousel-viewport {
+    flex: 1 1 auto;
+    min-width: 0;
+  }
+
+  /* Inside: float the arrows over the slides. */
+  &.iw-carousel-arrows-inside .iw-carousel-stage {
+    gap: 0;
+  }
+
+  &.iw-carousel-arrows-inside .iw-carousel-arrow {
+    position: absolute;
+    top: 50%;
+    z-index: 1;
+    transform: translateY(-50%);
+  }
+
+  &.iw-carousel-arrows-inside .iw-carousel-arrow-previous {
+    left: var(--iw-carousel-arrow-inset);
+  }
+
+  &.iw-carousel-arrows-inside .iw-carousel-arrow-next {
+    right: var(--iw-carousel-arrow-inset);
+  }
+
+  &.iw-carousel-vertical.iw-carousel-arrows-inside .iw-carousel-arrow {
+    top: auto;
+    right: auto;
+    left: 50%;
+    transform: translateX(-50%);
+  }
+
+  &.iw-carousel-vertical.iw-carousel-arrows-inside .iw-carousel-arrow-previous {
+    top: var(--iw-carousel-arrow-inset);
+  }
+
+  &.iw-carousel-vertical.iw-carousel-arrows-inside .iw-carousel-arrow-next {
+    bottom: var(--iw-carousel-arrow-inset);
+  }
+
+  /* Outside: the arrows sit beside the scrolling area, flex handles centring. */
+  &.iw-carousel-arrows-outside .iw-carousel-arrow {
+    position: static;
+    flex: 0 0 auto;
+  }
+
+  /* Chevrons drawn with borders, no icon font needed. */
+  .iw-carousel-chevron {
+    display: block;
+    width: 0;
+    height: 0;
+    border-top: var(--iw-carousel-arrow-chevron) solid transparent;
+    border-bottom: var(--iw-carousel-arrow-chevron) solid transparent;
+  }
+
+  .iw-carousel-arrow-previous .iw-carousel-chevron {
+    margin-right: 2px;
+    border-right: 7px solid currentcolor;
+  }
+
+  .iw-carousel-arrow-next .iw-carousel-chevron {
+    margin-left: 2px;
+    border-left: 7px solid currentcolor;
+  }
+
+  &.iw-carousel-vertical .iw-carousel-chevron {
+    border-right: none;
+    border-left: none;
+    border-inline: var(--iw-carousel-arrow-chevron) solid transparent;
+  }
+
+  &.iw-carousel-vertical .iw-carousel-arrow-previous .iw-carousel-chevron {
+    margin: 0 0 2px;
+    border-top: none;
+    border-bottom: 7px solid currentcolor;
+  }
+
+  &.iw-carousel-vertical .iw-carousel-arrow-next .iw-carousel-chevron {
+    margin: 2px 0 0;
+    border-top: 7px solid currentcolor;
+    border-bottom: none;
+  }
+
+  .iw-carousel-indicators {
+    display: flex;
+    justify-content: center;
+    gap: var(--iw-space-2);
+    padding: var(--iw-space-2);
+  }
+
+  .iw-carousel-indicator {
+    width: var(--iw-carousel-indicator-size);
+    height: var(--iw-carousel-indicator-size);
+    padding: 0;
+    border: none;
+    border-radius: var(--iw-radius-full);
+    background: var(--iw-carousel-indicator-color);
+    cursor: pointer;
+  }
+
+  .iw-carousel-indicator-current {
+    background: var(--iw-carousel-indicator-color-current);
+  }
+}
+
+/* Respect reduced motion: only animate paging when the user allows it. */
+@media (prefers-reduced-motion: no-preference) {
+  .iw-carousel .iw-carousel-viewport {
+    scroll-behavior: smooth;
+  }
+}