saudi-national-day-carousel 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,48 @@
+# Saudi National Day Carousel
+
+GitHub: [farhat-baaroun/saudi-national-day-carousel](https://github.com/farhat-baaroun/saudi-national-day-carousel)
+
+Storybook lives in a separate repo: [saudi-national-day-carousel-storybook](https://github.com/farhat-baaroun/saudi-national-day-carousel-storybook).
+
+React 18 hero carousel with a stacked wide deck, compact peek + swipe, and a standalone UMD build.
+
+The widget fills its parent. Layout uses container queries, not the viewport.
+
+Stories live in the sibling `saudi-national-day-carousel-storybook` package, not here.
+
+## React
+
+```tsx
+import { SaudiNationalDayCarousel } from "saudi-national-day-carousel";
+import "saudi-national-day-carousel/style.css";
+
+export function Hero() {
+  return (
+    <div style={{ width: "100%", height: 491 }}>
+      <SaudiNationalDayCarousel />
+    </div>
+  );
+}
+```
+
+## UMD / CDN
+
+After `npm publish`, jsDelivr and unpkg serve the UMD bundle:
+
+```html
+<div id="hero" style="width:100%;aspect-ratio:1440/491"></div>
+<script src="https://cdn.jsdelivr.net/npm/saudi-national-day-carousel/dist/saudi-national-day-carousel.umd.js"></script>
+<script>
+  SaudiNationalDayCarousel.mount("#hero", { autoplayMs: 6000 });
+</script>
+```
+
+Local demo: `demo/umd.html` (needs `npm run build` first).
+
+## Scripts
+
+| Command | Purpose |
+| --- | --- |
+| `npm run build` | ESM library + UMD widget |
+| `npm test` | Unit tests |
+| `npm publish` | Publish `dist/` to npm (then CDN) |

package/dist/animations/cssStrategy.d.ts

@@ -0,0 +1,2 @@
+import { AnimationStrategy } from '../core/types';
+export declare const cssAnimationStrategy: AnimationStrategy;

package/dist/components/ArrowButton.d.ts

@@ -0,0 +1,8 @@
+type ArrowButtonProps = {
+    direction: "previous" | "next";
+    onClick: () => void;
+    label: string;
+    hidden?: boolean;
+};
+export declare function ArrowButton({ direction, onClick, label, hidden }: ArrowButtonProps): import("react").JSX.Element;
+export {};

package/dist/components/AssetDeck.d.ts

@@ -0,0 +1 @@
+export declare function AssetDeck(): import("react").JSX.Element;

package/dist/components/Controls.d.ts

@@ -0,0 +1 @@
+export declare function Controls(): import("react").JSX.Element;

package/dist/components/Headline.d.ts

@@ -0,0 +1 @@
+export declare function Headline(): import("react").JSX.Element;

package/dist/components/Logo.d.ts

@@ -0,0 +1 @@
+export declare function Logo(): import("react").JSX.Element;

package/dist/components/Root.d.ts

@@ -0,0 +1,2 @@
+import { CarouselRootProps } from '../core/types';
+export declare function Root({ slides, initialIndex, animation, animationStrategy, onSlideChange, className, style, children, }: CarouselRootProps): import("react").JSX.Element;

package/dist/components/SaudiNationalDayCarousel.d.ts

@@ -0,0 +1,16 @@
+import { AssetDeck } from './AssetDeck';
+import { CarouselRootProps } from '../core/types';
+/**
+ * Saudi National Day hero carousel.
+ *
+ * Fills its parent. Wide parents show a staggered figure stack; compact
+ * parents (about 390×760) use a peek carousel that stops at the first and last slide.
+ */
+export declare function SaudiNationalDayCarousel(props: CarouselRootProps): import("react").JSX.Element;
+export declare namespace SaudiNationalDayCarousel {
+    var Root: typeof import("./Root").Root;
+    var Deck: typeof AssetDeck;
+    var Headline: typeof import("./Headline").Headline;
+    var Controls: typeof import("./Controls").Controls;
+    var Logo: typeof import("./Logo").Logo;
+}

package/dist/core/CarouselContext.d.ts

@@ -0,0 +1,13 @@
+import { ReactNode } from 'react';
+import { AnimationConfig, AnimationStrategy, CarouselApi, Slide } from './types';
+export type CarouselProviderProps = {
+    slides?: Slide[];
+    initialIndex?: number;
+    animation?: Partial<AnimationConfig>;
+    animationStrategy?: AnimationStrategy;
+    onSlideChange?: (index: number) => void;
+    paused?: boolean;
+    children: ReactNode;
+};
+export declare function CarouselProvider({ slides, initialIndex, animation, animationStrategy, onSlideChange, paused, children, }: CarouselProviderProps): import("react").JSX.Element;
+export declare function useCarousel(): CarouselApi;

package/dist/core/deckMotion.d.ts

@@ -0,0 +1,3 @@
+export declare function peekOffset(slideIndex: number, activeIndex: number, count: number): number | null;
+export declare function stackOffset(slideIndex: number, activeIndex: number, count: number): number;
+export declare function resolveSwipe(deltaX: number, threshold: number): -1 | 0 | 1;

package/dist/core/defaults.d.ts

@@ -0,0 +1,7 @@
+import { AnimationConfig } from './types';
+export declare const DEFAULT_ANIMATION: AnimationConfig;
+export declare const DEFAULT_TITLE = "\u0639\u0650\u0632\u0651\u0646\u0627";
+export declare const DEFAULT_INITIAL_INDEX = 5;
+export declare const DESIGN_WIDTH = 1440;
+export declare const DESIGN_HEIGHT = 491;
+export declare function mergeAnimationConfig(overrides?: Partial<AnimationConfig>): AnimationConfig;

package/dist/core/layout.d.ts

@@ -0,0 +1,3 @@
+/** Minimum inline room reserved for logo, title, and description. */
+export declare const COMPACT_COPY_MIN_PX = 352;
+export declare function isCompactLayout(width: number, height: number): boolean;

package/dist/core/prefersReducedMotion.d.ts

@@ -0,0 +1,2 @@
+export declare function prefersReducedMotion(): boolean;
+export declare function subscribeReducedMotion(onChange: (value: boolean) => void): () => void;

package/dist/core/types.d.ts

@@ -0,0 +1,57 @@
+import { CSSProperties, ReactNode } from 'react';
+export type Slide = {
+    id: string;
+    title?: string;
+    typewriter: string;
+    description?: string;
+    image: string;
+    imageAlt: string;
+    background?: string;
+    gradient?: string;
+    textColor?: string;
+    accentColor?: string;
+    patternColor?: string;
+    controlColor?: string;
+};
+export type AnimationConfig = {
+    durationMs: number;
+    easing: string;
+    typewriterMsPerChar: number;
+    autoplayMs: number | false;
+};
+export interface AnimationStrategy {
+    enter(el: HTMLElement, config: AnimationConfig): void | Promise<void>;
+    exit(el: HTMLElement, config: AnimationConfig): void | Promise<void>;
+}
+export type CarouselApi = {
+    slides: Slide[];
+    index: number;
+    goTo: (index: number) => void;
+    next: () => void;
+    prev: () => void;
+    setPaused: (paused: boolean) => void;
+    animation: AnimationConfig;
+    animationStrategy: AnimationStrategy;
+    reducedMotion: boolean;
+    compact: boolean;
+    canPrev: boolean;
+    canNext: boolean;
+    setCompact: (compact: boolean) => void;
+};
+export type CarouselRootProps = {
+    /** Override the six default National Day slides. */
+    slides?: Slide[];
+    /** Zero-based start slide. Defaults to Vision when using built-in slides. */
+    initialIndex?: number;
+    /** Motion, typewriter, and autoplay timing. */
+    animation?: Partial<AnimationConfig>;
+    /** Custom enter/exit strategy. Defaults to CSS classes. */
+    animationStrategy?: AnimationStrategy;
+    /** Fires after the active index changes. */
+    onSlideChange?: (index: number) => void;
+    className?: string;
+    style?: CSSProperties;
+    /** Replace the default logo / headline / controls / deck layout. */
+    children?: ReactNode;
+};
+export type MountOptions = Omit<CarouselRootProps, "children"> & Partial<AnimationConfig>;

package/dist/core/useCarouselState.d.ts

@@ -0,0 +1,16 @@
+export type UseCarouselStateOptions = {
+    slideCount: number;
+    initialIndex?: number;
+    autoplayMs?: number | false;
+    paused?: boolean;
+    reducedMotion?: boolean;
+    loop?: boolean;
+    onChange?: (index: number) => void;
+};
+export declare function wrapIndex(index: number, count: number): number;
+export declare function useCarouselState({ slideCount, initialIndex, autoplayMs, paused, reducedMotion, loop, onChange, }: UseCarouselStateOptions): {
+    index: number;
+    goTo: (nextIndex: number) => void;
+    next: () => void;
+    prev: () => void;
+};

package/dist/core/useCompactLayout.d.ts

@@ -0,0 +1,2 @@
+import { RefObject } from 'react';
+export declare function useCompactLayout(ref: RefObject<HTMLElement | null>, onChange: (compact: boolean) => void): void;

package/dist/core/useDeckSwipe.d.ts

@@ -0,0 +1,17 @@
+import { PointerEvent as ReactPointerEvent, RefObject } from 'react';
+type UseDeckSwipeOptions = {
+    next: () => void;
+    prev: () => void;
+    setPaused: (paused: boolean) => void;
+    reducedMotion: boolean;
+    canPrev?: boolean;
+    canNext?: boolean;
+    compact?: boolean;
+};
+export declare function useDeckSwipe(deckRef: RefObject<HTMLElement | null>, { next, prev, setPaused, reducedMotion, canPrev, canNext, compact, }: UseDeckSwipeOptions): {
+    onPointerDown: (event: ReactPointerEvent<HTMLElement>) => void;
+    onPointerMove: (event: ReactPointerEvent<HTMLElement>) => void;
+    onPointerUp: (event: ReactPointerEvent<HTMLElement>) => void;
+    onPointerCancel: (event: ReactPointerEvent<HTMLElement>) => void;
+};
+export {};

package/dist/core/useSlideTransition.d.ts

@@ -0,0 +1,2 @@
+import { RefObject } from 'react';
+export declare function useSlideTransition(ref: RefObject<HTMLElement | null>): void;

package/dist/index.d.ts

@@ -0,0 +1,11 @@
+export { SaudiNationalDayCarousel } from './components/SaudiNationalDayCarousel';
+export { Root as SaudiNationalDayCarouselRoot } from './components/Root';
+export { AssetDeck } from './components/AssetDeck';
+export { Headline } from './components/Headline';
+export { Controls } from './components/Controls';
+export { Logo } from './components/Logo';
+export { defaultSlides, VISION_GRADIENT } from './slides/defaultSlides';
+export { cssAnimationStrategy } from './animations/cssStrategy';
+export { mergeAnimationConfig, DEFAULT_ANIMATION, DEFAULT_TITLE, DEFAULT_INITIAL_INDEX } from './core/defaults';
+export { COMPACT_COPY_MIN_PX, isCompactLayout } from './core/layout';
+export type { Slide, AnimationConfig, AnimationStrategy, CarouselRootProps, CarouselApi, MountOptions, } from './core/types';