formica-ui-lib 1.0.149 → 1.0.151

package/README.md

@@ -1,17 +1,263 @@
-# formicaui
+# Formica UI
 
-This is the home of Formica's Storybook components for the UI
+This repository contains Formica's Storybook-based UI component library.
+
+The goal of this repo is to keep UI pieces:
+
+- reusable
+- easy to compose
+- easy to wire into a BFF or app layer
+- free from business logic
+
+If you are new to the codebase, read this file first. If you need the stricter engineering rules, read [CONTRIBUTING.md](./CONTRIBUTING.md).
+
+## What Lives Here
+
+This project is mainly for:
+
+- atoms, molecules, organisms, templates, and scenes
+- Storybook stories for those components
+- shared prop contracts and callback payload types
+
+This project is not where UI components should:
+
+- fetch data
+- handle routing
+- talk directly to APIs
+- make business decisions
+
+## Folder Basics
+
+- `src/stories/...`
+  UI components and Storybook-facing implementations
+- `src/componentProps/...`
+  prop contracts and shared exported types
+- `mocks/...`
+  mock data used by stories and scene simulations
+
+## Working Rule Of Thumb
+
+Think of most UI components as display components.
+
+Their job is to:
+
+- render data
+- accept callback props
+- emit typed payloads upward
+- keep only small visual state when needed
+
+Their job is not to:
+
+- decide where the app navigates
+- call APIs
+- manage app-wide state
+- invent behavior on their own
+
+## Coding Standards In Plain English
+
+### 1. Put props and types in their own files
+
+If a component needs props, create a dedicated prop file for it under `src/componentProps/...`.
+
+Do not define the full prop contract inline inside the component unless it is truly private and temporary.
+
+Good:
+
+```ts
+export type ImageGridProps = {
+  images: GridImage[];
+  onImageClick?: (payload: ImageGridClickPayload) => void;
+};
+```
+
+### 2. Keep UI components dumb
+
+A UI component should mostly just render what it is given.
+
+Good:
+
+- render text, images, layout, and controls
+- call `onClick`, `onChange`, `onSelect`, etc.
+
+Bad:
+
+- calling `fetch`
+- importing routing logic
+- mutating app-wide data
+- logging app behavior from deep inside a presentational component unless it is only a temporary local debug step
+
+### 3. Pass behavior down, emit events up
+
+The app layer, BFF simulation layer, or scene story should own behavior.
+
+The deeper UI component should only emit a typed callback.
+
+Example flow:
+
+1. story or scene owns the state
+2. scene passes callback props down
+3. item component calls the callback
+4. typed payload comes back up
+
+### 4. Use explicit callback names
+
+Prefer clear names over generic handlers.
+
+Good:
+
+- `onCartClick`
+- `onLoginClick`
+- `onPromoClick`
+- `onImageClick`
+- `onCountrySelect`
+
+Less preferred:
+
+- `onAction`
+- `onEvent`
+- `handleThing`
+
+### 5. Do not use `any`
+
+If a callback sends data upward, define a real payload type and export it.
+
+Good:
+
+```ts
+export type ImageGridClickPayload = {
+  image: GridImage;
+  index: number;
+};
+```
+
+## Storybook Standards
+
+### Stories should use `.stories.js`
+
+Use `.stories.js` files for Storybook stories in this repo.
+
+### Stories should use args
+
+Prefer `args`-based stories and simple templates.
+
+Avoid complex JSX-heavy story files unless there is a real need.
+
+### Stories must match the final prop contract
+
+If the component props change, update the story right away.
+
+Do not leave stale story args, controls, or fake props around.
+
+## Scene Stories
+
+Scene stories are special.
+
+They should act like a lightweight simulation of how the UI will behave when wired into a BFF or application layer.
+
+That means scene stories should often own:
+
+- selected values
+- visible/hidden state
+- click handlers
+- change handlers
+- log output for interaction testing
+
+In other words: if a child component needs a callback to feel real, the scene story should usually provide it.
+
+## Generic Layout Containers
+
+We now have a few reusable layout primitives:
+
+- `ContentContainer`
+- `ContentGrid`
+- `FlowRow`
+
+Use them when several components share the same layout pattern.
+
+Examples:
+
+- centered max-width wrappers
+- responsive content grids
+- rows of controls or logos with shared spacing
+
+Do not force everything into one generic container.
+
+A generic container is worth using when the shared part is structural:
+
+- width
+- spacing
+- columns
+- wrapping
+- alignment
+
+It is not the right tool when the component needs domain-specific rules.
+
+### Good use of a generic container
+
+- `ImageGrid` using `ContentGrid`
+- `DecorGrid` using `ContentGrid`
+
+### Bad use of a generic container
+
+- a grid deciding what happens when a card is clicked
+- a layout wrapper deciding navigation or selection logic
+
+## When To Use `ClickableCard`
+
+Use `ClickableCard` when a whole card or large visual surface acts as one click target.
+
+Examples:
+
+- an image tile that opens detail
+- a swatch card where clicking the image opens the decor
+
+Do not use `ClickableCard` when only a normal CTA inside the card is interactive.
+
+Examples:
+
+- a card with a single "Learn More" button
+- a card with a standard text link
+
+### Important rule
+
+The component that owns the clickable surface should own `ClickableCard`.
+
+Good:
+
+- `SwatchCard` uses `ClickableCard`
+- `ImageGrid` uses `ClickableCard` per image tile
+
+Bad:
+
+- `DecorGrid` wrapping every child in `ClickableCard`
+- `ContentGrid` trying to handle clicks
+
+## Atomic Design Guidance
+
+Try to keep responsibility at the right layer:
+
+- atoms
+  simple UI pieces and layout primitives
+- molecules
+  small composed patterns like `ClickableCard`
+- organisms
+  richer composed sections like grids, navs, banners, panels
+- scenes
+  higher-level composition and interaction simulation
+
+If a primitive starts learning too much about a domain concept, it is probably in the wrong layer.
 
 ## Branching / Git Workflow
 
-⚠️ **Direct commits to `main` are not allowed.** All work must be done in a feature branch created from `dev`.
+Direct commits to `main` are not allowed.
 
-### Create a feature branch from `dev`
+Create feature branches from `dev`.
 
-1. Checkout `dev` and pull the latest changes
-2. Create a new feature branch named `feature/YourFeature`
+### Create a feature branch from `dev`
 
-**Commands:**
+1. Checkout `dev`
+2. Pull the latest changes
+3. Create a feature branch named `feature/YourFeature`
 
 ```bash
 git fetch
@@ -19,3 +265,17 @@ git checkout dev
 git pull
 git checkout -b feature/YourFeature
 ```
+
+## Final Advice For Junior Devs
+
+If you are unsure where code should live, ask these questions:
+
+1. Is this layout or behavior?
+2. Does this component need to know app logic, or just render?
+3. Is this click target owned by the item, or by the container?
+4. Is this type reusable enough to belong in `componentProps`?
+5. Would this be easier to understand if the story owned the state instead?
+
+If you stay strict about those five questions, your changes will usually fit the codebase well.
+
+For the stricter rule set, examples, and review checklist, see [CONTRIBUTING.md](./CONTRIBUTING.md).

package/dist/componentProps/atoms/layout/ContentContainerProps.d.ts

@@ -0,0 +1,8 @@
+import React from "react";
+export type ContentContainerMaxWidth = "sm" | "md" | "lg" | "xl" | "2xl" | "4xl" | "6xl";
+export type ContentContainerProps = {
+    children?: React.ReactNode;
+    className?: string;
+    innerClassName?: string;
+    maxWidth?: ContentContainerMaxWidth;
+};

package/dist/componentProps/atoms/layout/ContentGridProps.d.ts

@@ -0,0 +1,12 @@
+import React from "react";
+import type { ContentContainerMaxWidth } from "./ContentContainerProps";
+export type ContentGridColumns = 1 | 2 | 3 | 4;
+export type ContentGridGap = "sm" | "md" | "lg" | "xl";
+export type ContentGridProps = {
+    children?: React.ReactNode;
+    className?: string;
+    gridClassName?: string;
+    maxWidth?: ContentContainerMaxWidth;
+    columns?: ContentGridColumns;
+    gap?: ContentGridGap;
+};

package/dist/componentProps/atoms/layout/FlowRowProps.d.ts

@@ -0,0 +1,12 @@
+import React from "react";
+export type FlowRowGap = "sm" | "md" | "lg" | "xl";
+export type FlowRowAlign = "start" | "center" | "end" | "stretch";
+export type FlowRowJustify = "start" | "center" | "end" | "between" | "around" | "evenly";
+export type FlowRowProps = {
+    children?: React.ReactNode;
+    className?: string;
+    gap?: FlowRowGap;
+    align?: FlowRowAlign;
+    justify?: FlowRowJustify;
+    wrap?: boolean;
+};

package/dist/componentProps/molecules/selectors/filterbar/DropdownFilterProps.d.ts

@@ -0,0 +1,5 @@
+import type { DropdownProps } from "../../../atoms/dropdown/DropdownProps";
+export type DropdownFilterProps = {
+    dropdownProps: DropdownProps;
+    className?: string;
+};

package/dist/componentProps/molecules/selectors/filterbar/FilterBarButtonProps.d.ts

@@ -0,0 +1,5 @@
+import type { ButtonProps } from "../../../atoms/buttons/button/ButtonProps";
+export type FilterBarButtonProps = {
+    buttonProps: ButtonProps;
+    className?: string;
+};

package/dist/componentProps/molecules/selectors/filterbar/FilterBarProps.d.ts

@@ -0,0 +1,6 @@
+import React from "react";
+export type FilterBarProps = {
+    children?: React.ReactNode;
+    className?: string;
+    barClassName?: string;
+};

package/dist/componentProps/molecules/selectors/filterbar/SearchFilterProps.d.ts

@@ -0,0 +1,5 @@
+import type { SearchBarProps } from "../../searchbar/SearchBarProps";
+export type SearchFilterProps = {
+    searchBarProps: SearchBarProps;
+    className?: string;
+};

package/dist/componentProps/organisms/imagegrid/ImageGridProps.d.ts

@@ -4,6 +4,11 @@ export type GridImage = Omit<React.ImgHTMLAttributes<HTMLImageElement>, "src" |
     alt: string;
     quality: number;
 };
+export type ImageGridClickPayload = {
+    image: GridImage;
+    index: number;
+};
 export interface ImageGridProps {
     images: GridImage[];
+    onImageClick?: (payload: ImageGridClickPayload) => void;
 }

package/dist/componentProps/scene/category/CategorySceneProps.d.ts

@@ -1,12 +1,18 @@
 import type { StandardCopyHeroProps } from "../../organisms/banner/standardcopyhero/StandardCopyHeroProps";
 import type { MultiButtonBarProps } from "../../molecules/selectors/multibuttonbar/MultiButtonBarProps";
-import type { SortAndFilterBarProps } from "../../molecules/selectors/sortandfilterbar/SortAndFilterBarProps";
+import type { FilterBarProps } from "../../molecules/selectors/filterbar/FilterBarProps";
+import type { FilterBarButtonProps } from "../../molecules/selectors/filterbar/FilterBarButtonProps";
+import type { DropdownFilterProps } from "../../molecules/selectors/filterbar/DropdownFilterProps";
+import type { SearchFilterProps } from "../../molecules/selectors/filterbar/SearchFilterProps";
 import type { DecorGridProps } from "../../organisms/decorgrid/DecorGridProps";
 import type { VerticalCheckboxListCollectionProps } from "../../organisms/verticalcheckboxlistcollection/VerticalCheckboxListCollectionProps";
 export type CategorySceneProps = {
     standardCopyHeroProps: StandardCopyHeroProps;
     multiButtonBarProps: MultiButtonBarProps;
-    sortAndSearchBarProps: SortAndFilterBarProps;
+    filterBarProps: FilterBarProps;
+    filterToggleButtonProps: FilterBarButtonProps;
+    sortDropdownFilterProps: DropdownFilterProps;
+    searchFilterProps: SearchFilterProps;
     verticalCheckboxListCollectionProps?: VerticalCheckboxListCollectionProps;
     decorGridProps: DecorGridProps;
 };

package/dist/componentProps/scene/gallery/GallerySceneProps.d.ts

@@ -1,10 +1,12 @@
 import type { StandardCopyHeroProps } from "../../organisms/banner/standardcopyhero/StandardCopyHeroProps";
 import type { MultiButtonBarProps } from "../../molecules/selectors/multibuttonbar/MultiButtonBarProps";
-import type { TripleDropdownBarProps } from "../../molecules/selectors/tripledropdownbar/TripleDropdownBarProps";
+import type { FilterBarProps } from "../../molecules/selectors/filterbar/FilterBarProps";
+import type { DropdownFilterProps } from "../../molecules/selectors/filterbar/DropdownFilterProps";
 import type { ImageGridProps } from "../../organisms/imagegrid/ImageGridProps";
 export type GallerySceneProps = {
     standardCopyHeroProps: StandardCopyHeroProps;
     multiButtonBarProps: MultiButtonBarProps;
-    tripleDropdownBarProps: TripleDropdownBarProps;
+    filterBarProps: FilterBarProps;
+    dropdownFilterPropsList: DropdownFilterProps[];
     imageGridProps: ImageGridProps;
 };