Skip to content
Merged
Show file tree
Hide file tree
Changes from 3 commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
7 changes: 7 additions & 0 deletions .changeset/carousel-snap-paging.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,7 @@
---
'@astryxdesign/core': patch
---

[feat] Carousel's `hasSnap` also takes `useSnapPaging()`, from `@astryxdesign/core/SnapPaging`: iOS paging on native snap's stops, under a finger and on a trackpad swipe. A flick moves one view, or one item with `useSnapPaging({pages: 'item'})`. A mouse wheel keeps native snapping. Only a carousel given the hook's value loads the pager, and `hasSnap` alone is unchanged.

@vjeux
7 changes: 7 additions & 0 deletions .changeset/use-snap-paging-example.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,7 @@
---
'@astryxdesign/cli': patch
---

[docs] A `useSnapPaging — Onboarding Pages` example block: onboarding cards in a Carousel with `hasSnap={useSnapPaging()}` move one view per flick, and a switch moves one card per flick through the hook's `pages` option. Copy it with `astryx template CarouselSnapPaging <path>`.

@vjeux
1 change: 1 addition & 0 deletions apps/sandbox/scripts/next-export-routes.json
Original file line number Diff line number Diff line change
Expand Up @@ -146,6 +146,7 @@
"/templates/CarouselCards/",
"/templates/CarouselShowcase/",
"/templates/CarouselSnap/",
"/templates/CarouselSnapPaging/",
"/templates/CenterHorizontal/",
"/templates/CenterInsideACard/",
"/templates/CenterShowcase/",
Expand Down
106 changes: 106 additions & 0 deletions apps/storybook/stories/Carousel.stories.tsx
Original file line number Diff line number Diff line change
Expand Up @@ -5,6 +5,7 @@ import type {Meta, StoryObj} from '@storybook/react';
import * as stylex from '@stylexjs/stylex';
import {Carousel} from '@astryxdesign/core/Carousel';
import type {CarouselHandle} from '@astryxdesign/core/Carousel';
import {useSnapPaging} from '@astryxdesign/core/SnapPaging';
import {Thumbnail} from '@astryxdesign/core/Thumbnail';
import {Card} from '@astryxdesign/core/Card';
import {Button} from '@astryxdesign/core/Button';
Expand Down Expand Up @@ -53,6 +54,27 @@ const styles = stylex.create({
borderRadius: radiusVars['--radius-element'],
flexShrink: 0,
},
pagingFrame: {
width: 300,
},
pagingItem: {
display: 'flex',
alignItems: 'center',
justifyContent: 'center',
height: 120,
borderRadius: radiusVars['--radius-element'],
backgroundColor: colorVars['--color-background-muted'],
color: colorVars['--color-text-primary'],
fontFamily: typographyVars['--font-family-body'],
fontSize: 24,
fontWeight: 600,
},
oneUp: {
width: 300,
},
threeUp: {
width: `calc((300px - 2 * ${spacingVars['--spacing-2']}) / 3)`,
},
label: {
fontSize: 12,
color: colorVars['--color-text-secondary'],
Expand Down Expand Up @@ -468,3 +490,87 @@ export const SingleItem: Story = {
</div>
),
};

type PagingMode = 'snap' | 'paging' | 'item';

/**
* A 300 px carousel of numbered items, snapping natively (`snap`) or with snap
* paging: one view per flick (`paging`) or one item (`item`).
*/
function PagingCarousel({
layout,
count,
mode,
}: {
layout: '1-up' | '3-up';
count: number;
mode: PagingMode;
}) {
// One value: Carousel keeps the value it first attached, and a new `pages`
// applies from the next flick.
const paging = useSnapPaging({pages: mode === 'item' ? 'item' : 'view'});
const hasSnap = mode === 'snap' ? true : paging;
return (
<div {...stylex.props(styles.pagingFrame)}>
<Carousel
gap={layout === '1-up' ? 0 : 2}
hasSnap={hasSnap}
aria-label="Numbered items">
{Array.from({length: count}, (_, i) => (
<div
key={i}
data-item={i}
{...stylex.props(
styles.pagingItem,
layout === '1-up' ? styles.oneUp : styles.threeUp,
)}>
{i + 1}
</div>
))}
</Carousel>
</div>
);
}

const pagingArgTypes = {
mode: {
control: {type: 'select' as const},
options: ['snap', 'paging', 'item'],
description:
'hasSnap (native snap), hasSnap={useSnapPaging()} (one view per flick) or hasSnap={useSnapPaging({pages: "item"})}',
},
};

type PagingStory = StoryObj<{mode: PagingMode}>;

export const SnapPagingOneUp: PagingStory = {
name: 'Snap Paging: One Item per View',
argTypes: pagingArgTypes,
args: {mode: 'paging'},
render: ({mode}) => <PagingCarousel layout="1-up" count={5} mode={mode} />,
};

export const SnapPagingThreeUp: PagingStory = {
name: 'Snap Paging: Three Items per View',
argTypes: pagingArgTypes,
args: {mode: 'paging'},
render: ({mode}) => <PagingCarousel layout="3-up" count={9} mode={mode} />,
};

export const SnapPagingPartialLastPage: PagingStory = {
name: 'Snap Paging: Partial Last Page',
argTypes: pagingArgTypes,
args: {mode: 'paging'},
render: ({mode}) => <PagingCarousel layout="3-up" count={7} mode={mode} />,
};

export const SnapPagingRightToLeft: PagingStory = {
name: 'Snap Paging: Right to Left',
argTypes: pagingArgTypes,
args: {mode: 'paging'},
render: ({mode}) => (
<div dir="rtl">
<PagingCarousel layout="3-up" count={9} mode={mode} />
</div>
),
};
29 changes: 16 additions & 13 deletions docs/specs/components/Carousel/Carousel.spec.md

Large diffs are not rendered by default.

10 changes: 10 additions & 0 deletions internal/shadcn-registry/routes.lock.json
Original file line number Diff line number Diff line change
Expand Up @@ -3836,6 +3836,11 @@
"path": "examples/use-scrollable-area/activity-log-panel",
"aliases": []
},
{
"name": "example-use-snap-paging-onboarding-pages",
"path": "examples/use-snap-paging/onboarding-pages",
"aliases": []
},
{
"name": "example-use-streaming-text-streaming-response",
"path": "examples/use-streaming-text/streaming-response",
Expand Down Expand Up @@ -4176,6 +4181,11 @@
"path": "hooks/use-scrollable-area",
"aliases": []
},
{
"name": "hook-use-snap-paging",
"path": "hooks/use-snap-paging",
"aliases": []
},
{
"name": "hook-use-streaming-text",
"path": "hooks/use-streaming-text",
Expand Down
Original file line number Diff line number Diff line change
@@ -0,0 +1,14 @@
// Copyright (c) Meta Platforms, Inc. and affiliates.

/** @type {import('@astryxdesign/cli/authoring').TemplateDoc} */
export const doc = {
type: 'block',
exampleFor: 'useSnapPaging',
name: 'useSnapPaging — Onboarding Pages',
displayName: 'useSnapPaging — Onboarding Pages',
description:
"Onboarding cards in a Carousel with hasSnap={useSnapPaging()}: under a finger or a trackpad swipe, each flick moves one view and rests on a card's start edge. A switch picks one view or one card per flick through the hook's pages option.",
isReady: true,
aspectRatio: 4 / 3,
componentsUsed: ['Carousel', 'Card', 'Layout', 'Switch', 'Text'],
};
Original file line number Diff line number Diff line change
@@ -0,0 +1,49 @@
// Copyright (c) Meta Platforms, Inc. and affiliates.

'use client';

import {useState} from 'react';
import {Card} from '@astryxdesign/core/Card';
import {Carousel} from '@astryxdesign/core/Carousel';
import {Stack} from '@astryxdesign/core/Layout';
import {useSnapPaging} from '@astryxdesign/core/SnapPaging';
import {Switch} from '@astryxdesign/core/Switch';
import {Text} from '@astryxdesign/core/Text';

const SCREENS = [
{title: 'Welcome', body: 'Swipe to see what is new.'},
{title: 'Shared albums', body: 'Invite friends to add their photos.'},
{title: 'Memories', body: 'See a day from years ago.'},
{title: 'Search', body: 'Find a photo by what is in it.'},
{title: 'All set', body: 'Your library is ready.'},
];

export default function CarouselSnapPaging() {
const [isOneCard, setIsOneCard] = useState(false);
// A flick moves one view, or one card with {pages: 'item'}.
const paging = useSnapPaging({pages: isOneCard ? 'item' : 'view'});

return (
<Stack direction="vertical" gap={3} style={{maxWidth: 520, padding: 8}}>
<Switch
label="One card per flick"
value={isOneCard}
onChange={setIsOneCard}
/>
<Carousel gap={2} hasSnap={paging} aria-label="Onboarding">
{SCREENS.map(screen => (
<Card key={screen.title} width={220} minHeight={160}>
<Stack direction="vertical" gap={1}>
<Text type="body" weight="bold">
{screen.title}
</Text>
<Text type="body" color="secondary">
{screen.body}
</Text>
</Stack>
</Card>
))}
</Carousel>
</Stack>
);
}
17 changes: 16 additions & 1 deletion packages/core/api-report.md

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

5 changes: 5 additions & 0 deletions packages/core/package.json
Original file line number Diff line number Diff line change
Expand Up @@ -579,6 +579,11 @@
"types": "./dist/Slider/index.d.ts",
"default": "./dist/Slider/index.js"
},
"./SnapPaging": {
"source": "./src/SnapPaging/index.ts",
"types": "./dist/SnapPaging/index.d.ts",
"default": "./dist/SnapPaging/index.js"
},
"./Spinner": {
"source": "./src/Spinner/index.ts",
"types": "./dist/Spinner/index.d.ts",
Expand Down
7 changes: 4 additions & 3 deletions packages/core/src/Carousel/Carousel.doc.mjs
Original file line number Diff line number Diff line change
Expand Up @@ -12,6 +12,7 @@ export const docs = {
'Carousel scrolls a row of items horizontally when they overflow the available width. Use it for card grids, image galleries, product lists, or any set of items that should be browsable without taking up the full page.',
bestPractices: [
{guidance: true, description: 'Enable scroll-snap when each item should land precisely at the start edge, like a gallery or product list.'},
{guidance: true, description: "For iOS paging under a finger and on a trackpad swipe, pass hasSnap={useSnapPaging()} from @astryxdesign/core/SnapPaging. A flick moves one view, or one item with useSnapPaging({pages: 'item'}). A mouse wheel keeps native snapping. Only a carousel given it loads the paging code."},
{guidance: true, description: 'Reach for hasLoop on small, cyclable sets like a photo gallery, where wrapping past the last item back to the first feels natural.'},
{guidance: true, description: 'Always provide an aria-label that describes what the carousel contains, like "Featured products" or "Team members".'},
{guidance: true, description: 'Carousel implements the WAI-ARIA APG carousel pattern (https://www.w3.org/WAI/ARIA/apg/patterns/carousel/) without auto-rotation: the region is labelled and carries aria-roledescription="carousel", each item is a group named "Slide N of M", and the scroll container is a tab stop while its content overflows, so keyboard users can pan it with the arrow keys; while everything fits it stays out of the tab order.'},
Expand All @@ -34,7 +35,7 @@ export const docs = {
{name: 'hasButtons', type: 'boolean', description: 'Show prev/next navigation buttons when content is scrollable.', default: 'true'},
{name: 'hasEdgeFade', type: 'boolean', description: 'Show a gradient edge-fade mask when content overflows, signalling that more items exist off-screen.', default: 'true'},
{name: 'hasLoop', type: 'boolean', description: 'Wrap-around scrolling: next at the end scrolls to the start, prev at the start scrolls to the end. Buttons stay visible at both edges. Only engages when content overflows.', default: 'false'},
{name: 'hasSnap', type: 'boolean', description: 'Enable scroll-snap so each child snaps to the start edge.', default: 'false'},
{name: 'hasSnap', type: 'boolean | SnapPaging', description: "Snap each child to the start edge. hasSnap uses native CSS scroll snap. hasSnap={useSnapPaging()} adds iOS paging under a finger and on a trackpad swipe, on the same stops: a flick moves one view, or one item with useSnapPaging({pages: 'item'}). Only that value loads the paging code.", default: 'false'},
{name: 'padding', type: '0 | 0.5 | 1 | 1.5 | 2 | 3 | 4 | 5 | 6 | 8 | 10', description: 'Inline padding inside the scroll container, with matching scroll-padding so snap points align to the content edge.'},
{name: 'aria-label', type: 'string', description: 'Accessible label for the carousel region.', default: "\'Carousel\'"},
{name: 'ref', type: 'React.Ref<HTMLDivElement>', description: 'Ref forwarded to the root element.'},
Expand Down Expand Up @@ -84,7 +85,7 @@ export const docsZh = {
hasButtons: '内容可滚动时显示上一个/下一个导航按钮。',
hasEdgeFade: '内容溢出时显示渐变边缘遮罩,提示屏幕外还有更多项目。',
hasLoop: '环绕滚动:在末尾按"下一个"回到开头,在开头按"上一个"跳到末尾。按钮在两端始终可见。仅在内容溢出时生效。',
hasSnap: '启用滚动吸附,使每个子元素吸附到起始边缘。',
hasSnap: "使每个子元素吸附到起始边缘。hasSnap 使用原生 CSS 滚动吸附。hasSnap={useSnapPaging()} 在相同吸附点上增加手指和触控板轻扫下的 iOS 分页:一次轻扫移动一屏,或用 useSnapPaging({pages: 'item'}) 移动一项。只有该值会加载分页代码。",
padding: '滚动容器内的内联内边距,并设置匹配的 scroll-padding,使吸附点与内容边缘对齐。',
'aria-label': '轮播区域的无障碍标签。',
handleRef: '命令式句柄,暴露 scrollNext()、scrollPrev()、scrollTo(index)、canScrollNext() 和 canScrollPrev() 以进行编程式滚动控制。',
Expand Down Expand Up @@ -114,7 +115,7 @@ export const docsDense = {
hasButtons: 'prev/next buttons when content is scrollable',
hasEdgeFade: 'gradient edge-fade mask on overflow',
hasLoop: 'wrap-around: next at end -> start, prev at start -> end; buttons stay visible; only when overflowing',
hasSnap: 'scroll-snap; children snap to start edge',
hasSnap: "scroll-snap; children snap to start edge. hasSnap={useSnapPaging()}: iOS paging under a finger or trackpad swipe, one view per flick ({pages: 'item'}: one item); only that value loads the pager",
padding: 'inline padding; scroll-padding keeps snap points on content edge',
'aria-label': 'accessible label for carousel region',
handleRef: 'imperative handle: scrollNext/scrollPrev/scrollTo(index)/canScrollNext/canScrollPrev',
Expand Down
Loading