react-ternary-be-gone 0.1.5 → 0.2.0

package/README.md

@@ -10,7 +10,91 @@ npm install react-ternary-be-gone
 yarn add react-ternary-be-gone
 ```
 
+TypeScript definitions are bundled - no separate `@types/` package needed.
 
+## Two APIs
+
+This package ships two sets of components that cover the same ground:
+
+- **`<Show>`, `<For>`, `<Switch>`/`<Match>`** - focused, single-purpose
+  primitives. They hand the checked value back through a render prop, so
+  TypeScript narrows it exactly like `user && <p>{user.name}</p>` does. They
+  use no hooks, so they work inside React Server Components.
+- **`<Conditional>`** - the original all-in-one component (condition,
+  iteration, switch/case and if/else-if in one prop bag). Fully supported and
+  not going anywhere, but `when`/`each` can't be narrowed by TypeScript
+  (one prop bag has to cover five modes), and it uses hooks, so it needs a
+  client component boundary.
+
+New code is better off with the focused primitives. Existing `<Conditional>`
+code keeps working unchanged.
+
+```javascript
+// Focused primitives - narrow, RSC-safe
+import { Show, For, Switch, Match } from 'react-ternary-be-gone';
+
+<Show when={user} fallback={<Login />}>
+  {(u) => <p>{u.name}</p>}
+</Show>
+
+<For each={users} empty={<p>No users.</p>}>
+  {(user) => <Row key={user.id} {...user} />}
+</For>
+
+<Switch fallback={<p>Unknown.</p>}>
+  <Match when={status === 'loading'}><Spinner /></Match>
+  <Match when={status === 'error'}><Alert /></Match>
+</Switch>
+```
+
+### `<Show>`
+
+Renders `children` when `when` is truthy, `fallback` otherwise. `children`
+may be a plain node, or a function receiving the truthy value - which
+TypeScript narrows to a non-nullish type.
+
+```javascript
+<Show when={user} fallback={<p>Not signed in.</p>}>
+  {(u) => <p>{u.name}</p>}
+</Show>
+```
+
+### `<For>`
+
+Iterates `each`, calling `children(item, index, items)` per entry. Supports
+`filter`, `sort`, `limit`, `reverse`, `keyExtractor`, `empty`, `fallback`
+and `wrapper`. A nullish `each` (`each={data?.items}` before a fetch
+resolves) renders `empty` rather than crashing.
+
+Unlike `<Conditional each>`, `children` must be a function - that removes a
+whole class of mistake instead of guarding against it.
+
+```javascript
+<For each={users} filter={(u) => u.active} sort={sortBy('name')} wrapper="ul">
+  {(user) => <li key={user.id}>{user.name}</li>}
+</For>
+```
+
+`<For>` deliberately leaves out `animate`, `debug` and `onRender`; use
+`<Conditional each={...}>` if you need those.
+
+### `<Switch>` / `<Match>`
+
+Renders the first `<Match>` whose `when` is truthy, or `<Switch>`'s
+`fallback` if none match - an if/else-if/else chain as markup. `<Match>`
+children can also be a function, narrowing `when` the way `<Show>` does.
+
+```javascript
+<Switch fallback={<p>Unknown status.</p>}>
+  <Match when={status === 'loading'}><Spinner /></Match>
+  <Match when={error}>{(e) => <Alert>{e.message}</Alert>}</Match>
+  <Match when={data}>{(d) => <Table rows={d.rows} />}</Match>
+</Switch>
+```
+
+`<Match when={...}>` takes a boolean condition per branch. To match one
+value against several cases, use `<Conditional switch={value}>` with
+`<Case when="a">` - a separate feature documented below.
 
 ## Usage
 
@@ -86,13 +170,13 @@ const status = 'success';
 
 <Conditional>
   <If when={status === 'loading'}>
-    <p>Yükleniyor...</p>
+    <p>Loading...</p>
   </If>
   <ElseIf when={status === 'success'}>
-    <p>Başarılı!</p>
+    <p>Success!</p>
   </ElseIf>
   <Else>
-    <p>Durum bilinmiyor.</p>
+    <p>Status unknown.</p>
   </Else>
 </Conditional>
 ```
@@ -107,7 +191,7 @@ const users = [{ id: 1, name: 'Alice', active: true }, { id: 2, name: 'Bob', act
     {(user) => <p>{user.name}</p>}
   </If>
   <Else>
-    <p>Kullanıcı yok.</p>
+    <p>No users found.</p>
   </Else>
 </Conditional>
 ```
@@ -127,9 +211,9 @@ import Conditional, { Case } from 'react-ternary-be-gone';
 const value = 'b';
 
 <Conditional switch={value}>
-  <Case when="a">A seçildi</Case>
-  <Case when="b">B seçildi</Case>
-  <Case default>Hiçbiri seçilmedi</Case>
+  <Case when="a">A selected</Case>
+  <Case when="b">B selected</Case>
+  <Case default>None selected</Case>
 </Conditional>
 ```
 
@@ -450,6 +534,15 @@ A callback function that is called after the component renders. Provides informa
 
 ### Advanced Condition Evaluation Props
 
+> **Deprecated.** These still work and aren't scheduled for removal, but a
+> plain expression in `when` is shorter and reads better:
+> `when={a > b}` instead of `gt={{ value: a, target: b }}`. They're marked
+> `@deprecated` in the TypeScript definitions, so editors will flag them.
+>
+> Note that these props did nothing at all before v0.1.4 - the condition was
+> ignored and children always rendered. If you wrote code against the broken
+> behaviour, check it.
+
 These props allow for more complex conditional checks without needing to define a separate `when` prop.  Only one of these props should be used at a time.
 
 #### `gt` (Greater Than)

package/dist/Case.js

@@ -5,4 +5,4 @@ Object.defineProperty(exports, "__esModule", {
 });
 exports.default = void 0;
 var _markers = require("./markers");
-var _default = exports.default = (0, _markers.createMarker)('Case', _markers.CASE);
+var _default = exports.default = (0, _markers.createMarker)('Case', _markers.CASE, 'Conditional');

package/dist/Conditional.js

@@ -6,47 +6,8 @@ Object.defineProperty(exports, "__esModule", {
 exports.default = void 0;
 var _react = _interopRequireWildcard(require("react"));
 var _markers = require("./markers");
+var _shared = require("./shared");
 function _interopRequireWildcard(e, t) { if ("function" == typeof WeakMap) var r = new WeakMap(), n = new WeakMap(); return (_interopRequireWildcard = function (e, t) { if (!t && e && e.__esModule) return e; var o, i, f = { __proto__: null, default: e }; if (null === e || "object" != typeof e && "function" != typeof e) return f; if (o = t ? n : r) { if (o.has(e)) return o.get(e); o.set(e, f); } for (const t in e) "default" !== t && {}.hasOwnProperty.call(e, t) && ((i = (o = Object.defineProperty) && Object.getOwnPropertyDescriptor(e, t)) && (i.get || i.set) ? o(f, t, i) : f[t] = e[t]); return f; })(e, t); }
-// Pure helper: apply filter/sort/reverse/limit to an `each` array without
-// mutating the caller's array (Array.prototype.sort/reverse mutate in place,
-// so every step works off a copy).
-const processArray = (array, {
-  filter,
-  sort,
-  reverse,
-  limit
-}) => {
-  if (!Array.isArray(array)) return [];
-  let result = [...array];
-  if (typeof filter === 'function') result = result.filter(filter);
-  if (typeof sort === 'function') result = result.sort(sort);
-  if (reverse) result = result.reverse();
-  if (typeof limit === 'number') result = result.slice(0, limit);
-  return result;
-};
-
-// Pure helper: render one React.Fragment per item, guarding the render-prop
-// call so static children (a plain element instead of a function) don't
-// crash when they reach an iteration path.
-const renderIterableChildren = (items, children, keyExtractor) => items.map((item, index) => /*#__PURE__*/_react.default.createElement(_react.default.Fragment, {
-  key: keyExtractor ? keyExtractor(item, index) : index
-}, typeof children === 'function' ? children(item, index, items) : children));
-
-// `React.Children.toArray` flattens arrays produced by `.map()`, but an
-// author-written `<>...</>` around a set of branches is itself a single
-// Fragment element in the tree - its contents need an explicit unwrap or
-// `<If>`/`<ElseIf>`/`<Else>`/`<Case>` inside one are never seen as branches.
-const flattenBranches = children => {
-  const result = [];
-  _react.default.Children.toArray(children).forEach(child => {
-    if (child && child.type === _react.default.Fragment) {
-      result.push(...flattenBranches(child.props.children));
-    } else {
-      result.push(child);
-    }
-  });
-  return result;
-};
 const Conditional = props => {
   const {
     when,
@@ -167,7 +128,7 @@ const Conditional = props => {
 
   // Array processing
   const processedArray = (0, _react.useMemo)(() => {
-    const result = processArray(each, {
+    const result = (0, _shared.processArray)(each, {
       filter,
       sort,
       reverse,
@@ -220,7 +181,7 @@ const Conditional = props => {
   // while `status` is legitimately undefined before data loads, the same
   // reasoning as the `each` presence check above.
   if ('switch' in props) {
-    const caseChildren = flattenBranches(children).filter(child => child && (0, _markers.markerKindOf)(child) === _markers.CASE);
+    const caseChildren = (0, _markers.flattenBranches)(children).filter(child => child && (0, _markers.markerKindOf)(child) === _markers.CASE);
     // `.find()` stops at the first hit, matching how a real `switch` picks
     // the first matching branch instead of the last one.
     const matchedCase = caseChildren.find(child => !child.props.default && child.props.when === switchValue);
@@ -235,7 +196,7 @@ const Conditional = props => {
   }
 
   // If-ElseIf-Else logic
-  const branches = flattenBranches(children).filter(child => child && [_markers.IF, _markers.ELSE_IF, _markers.ELSE].includes((0, _markers.markerKindOf)(child)));
+  const branches = (0, _markers.flattenBranches)(children).filter(child => child && [_markers.IF, _markers.ELSE_IF, _markers.ELSE].includes((0, _markers.markerKindOf)(child)));
   if (branches.length > 0) {
     let rendered = fallback;
     for (const branch of branches) {
@@ -256,13 +217,13 @@ const Conditional = props => {
       const matches = kind === _markers.ELSE || Boolean(branchWhen);
       if (!matches) continue;
       if ('each' in branch.props) {
-        const items = processArray(branchEach, {
+        const items = (0, _shared.processArray)(branchEach, {
           filter: branchFilter,
           sort: branchSort,
           reverse: branchReverse,
           limit: branchLimit
         });
-        rendered = items.length === 0 ? branchEmpty || branchFallback || null : /*#__PURE__*/_react.default.createElement(BranchWrapper, null, renderIterableChildren(items, branchChildren, branchKeyExtractor));
+        rendered = items.length === 0 ? branchEmpty || branchFallback || null : /*#__PURE__*/_react.default.createElement(BranchWrapper, null, (0, _shared.renderIterableChildren)(items, branchChildren, branchKeyExtractor));
       } else {
         rendered = /*#__PURE__*/_react.default.createElement(BranchWrapper, null, branchChildren);
       }
@@ -281,7 +242,7 @@ const Conditional = props => {
     if (processedArray.length === 0) {
       return empty || fallback;
     }
-    const elements = renderIterableChildren(processedArray, children, keyExtractor);
+    const elements = (0, _shared.renderIterableChildren)(processedArray, children, keyExtractor);
     // React.Fragment rejects unknown props like `className`, so the default
     // wrapper is swapped for a real host element whenever `animate` needs
     // somewhere to put the class.
@@ -295,7 +256,7 @@ const Conditional = props => {
   if (hasCondition && hasIteration) {
     if (!evaluateCondition) return fallback;
     if (processedArray.length === 0) return empty || fallback;
-    const elements = renderIterableChildren(processedArray, children, keyExtractor);
+    const elements = (0, _shared.renderIterableChildren)(processedArray, children, keyExtractor);
     return /*#__PURE__*/_react.default.createElement(Wrapper, null, elements);
   }
   return /*#__PURE__*/_react.default.createElement(Wrapper, null, children);

package/dist/Else.js

@@ -5,4 +5,4 @@ Object.defineProperty(exports, "__esModule", {
 });
 exports.default = void 0;
 var _markers = require("./markers");
-var _default = exports.default = (0, _markers.createMarker)('Else', _markers.ELSE);
+var _default = exports.default = (0, _markers.createMarker)('Else', _markers.ELSE, 'Conditional');

package/dist/ElseIf.js

@@ -5,4 +5,4 @@ Object.defineProperty(exports, "__esModule", {
 });
 exports.default = void 0;
 var _markers = require("./markers");
-var _default = exports.default = (0, _markers.createMarker)('ElseIf', _markers.ELSE_IF);
+var _default = exports.default = (0, _markers.createMarker)('ElseIf', _markers.ELSE_IF, 'Conditional');

package/dist/For.js

@@ -0,0 +1,56 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.default = void 0;
+var _react = _interopRequireDefault(require("react"));
+var _shared = require("./shared");
+var _markers = require("./markers");
+function _interopRequireDefault(e) { return e && e.__esModule ? e : { default: e }; }
+/**
+ * Iterates `each`, rendering `children(item, index, items)` for each entry.
+ *
+ * Unlike `<Conditional each={x}>`, `children` here must be a function - not
+ * also a static ReactNode. That removes an entire class of bug (a render-prop
+ * call landing on something that isn't a function) by construction instead
+ * of by guarding against it.
+ *
+ * `each={undefined}`/`each={null}` (e.g. `each={data?.items}` before a
+ * fetch resolves) are treated as an empty list, rendering `empty` (or
+ * `fallback`) rather than crashing.
+ *
+ *   <For each={users} empty={<p>No users.</p>}>
+ *     {(user) => <p key={user.id}>{user.name}</p>}
+ *   </For>
+ *
+ * No hooks, no browser-only APIs: safe to call from a Server Component.
+ */
+const For = ({
+  each,
+  children,
+  fallback = null,
+  empty = null,
+  keyExtractor = (item, index) => index,
+  filter = null,
+  sort = null,
+  limit = null,
+  reverse = false,
+  wrapper: Wrapper = _react.default.Fragment
+}) => {
+  if (process.env.NODE_ENV !== 'production' && typeof children !== 'function') {
+    (0, _markers.warnOnce)('[react-ternary-be-gone] <For> expects `children` to be a function: ' + '(item, index, items) => ReactNode.');
+  }
+  const items = (0, _shared.processArray)(each, {
+    filter,
+    sort,
+    reverse,
+    limit
+  });
+  if (items.length === 0) {
+    return empty || fallback;
+  }
+  const elements = (0, _shared.renderIterableChildren)(items, children, keyExtractor);
+  return /*#__PURE__*/_react.default.createElement(Wrapper, null, elements);
+};
+var _default = exports.default = For;

package/dist/If.js

@@ -5,4 +5,4 @@ Object.defineProperty(exports, "__esModule", {
 });
 exports.default = void 0;
 var _markers = require("./markers");
-var _default = exports.default = (0, _markers.createMarker)('If', _markers.IF);
+var _default = exports.default = (0, _markers.createMarker)('If', _markers.IF, 'Conditional');

package/dist/Match.js

@@ -0,0 +1,8 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.default = void 0;
+var _markers = require("./markers");
+var _default = exports.default = (0, _markers.createMarker)('Match', _markers.MATCH, 'Switch');

package/dist/Show.js

@@ -0,0 +1,30 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.default = void 0;
+/**
+ * Renders `children` when `when` is truthy, `fallback` otherwise.
+ *
+ * Prefer this over `<Conditional when={x}>` when the branch needs the value
+ * itself: `children` may be a function that receives `when`, which
+ * TypeScript narrows to a non-nullish type in the .d.ts - exactly what
+ * `x && <Foo x={x} />` gives you for free and `<Conditional>` cannot,
+ * because it never hands the value back.
+ *
+ *   <Show when={user} fallback={<Login />}>
+ *     {(u) => <p>{u.name}</p>}
+ *   </Show>
+ *
+ * No hooks, no browser-only APIs: safe to call from a Server Component.
+ */
+const Show = ({
+  when,
+  children,
+  fallback = null
+}) => {
+  if (!when) return fallback;
+  return typeof children === 'function' ? children(when) : children;
+};
+var _default = exports.default = Show;

package/dist/Switch.js

@@ -0,0 +1,38 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.default = void 0;
+var _markers = require("./markers");
+/**
+ * Renders the first `<Match when={...}>` whose condition is truthy, or
+ * `fallback` if none match - a chain of if/else-if/else expressed as
+ * markup instead of nested ternaries.
+ *
+ *   <Switch fallback={<p>Unknown.</p>}>
+ *     <Match when={status === 'loading'}><Spinner /></Match>
+ *     <Match when={status === 'error'}>{() => <Alert>{error}</Alert>}</Match>
+ *   </Switch>
+ *
+ * `when` here is a boolean condition per branch, same as `<If>/<ElseIf>`.
+ * For matching one value against several cases, `<Conditional switch={value}>`
+ * with `<Case when="a">` remains the right tool - it's a different, unrelated
+ * feature that happens to share the word "switch".
+ *
+ * No hooks, no browser-only APIs: safe to call from a Server Component.
+ */
+const Switch = ({
+  children,
+  fallback = null
+}) => {
+  const branches = (0, _markers.flattenBranches)(children).filter(child => child && (0, _markers.markerKindOf)(child) === _markers.MATCH);
+  const winner = branches.find(child => Boolean(child.props.when));
+  if (!winner) return fallback;
+  const {
+    when,
+    children: branchChildren
+  } = winner.props;
+  return typeof branchChildren === 'function' ? branchChildren(when) : branchChildren;
+};
+var _default = exports.default = Switch;

package/dist/index.d.ts

@@ -0,0 +1,185 @@
+import * as React from 'react';
+
+/** Every value JavaScript treats as falsy, minus `NaN` (not its own type). */
+type Falsy = false | 0 | '' | null | undefined;
+
+// ---------------------------------------------------------------------------
+// Show / For / Switch / Match
+//
+// The typed, narrowing-friendly primitives. Prefer these in new code -
+// `<Conditional>` below stays fully supported, but `when`/`each` on it are
+// typed as `unknown`/`unknown[]` because one prop bag has to cover five
+// different modes, so TypeScript can't narrow anything inside its children.
+// Show/For/Match hand the checked value back through a render-prop instead,
+// which narrows exactly like `value && children(value)` does natively.
+// ---------------------------------------------------------------------------
+
+export interface ShowProps<T> {
+  when: T | Falsy;
+  /** A plain node, or a function receiving the truthy, narrowed `when`. */
+  children: React.ReactNode | ((value: Exclude<T, Falsy>) => React.ReactNode);
+  fallback?: React.ReactNode;
+}
+/** Renders `children` when `when` is truthy, `fallback` otherwise. */
+export function Show<T>(props: ShowProps<T>): React.ReactElement | null;
+
+export interface ForProps<T> {
+  each: readonly T[] | null | undefined;
+  children: (item: T, index: number, items: readonly T[]) => React.ReactNode;
+  fallback?: React.ReactNode;
+  /** Rendered when `each` is empty; falls back to `fallback` if omitted. */
+  empty?: React.ReactNode;
+  keyExtractor?: (item: T, index: number) => React.Key;
+  filter?: (item: T) => boolean;
+  sort?: (a: T, b: T) => number;
+  limit?: number;
+  reverse?: boolean;
+  /** Host element or component to wrap the rendered items in. @default React.Fragment */
+  wrapper?: React.ElementType;
+}
+/** Renders `children(item, index, items)` for each entry of `each`. */
+export function For<T>(props: ForProps<T>): React.ReactElement | null;
+
+export interface SwitchProps {
+  /** `<Match>` elements (optionally inside a fragment or produced by `.map()`). */
+  children: React.ReactNode;
+  fallback?: React.ReactNode;
+}
+/**
+ * Renders the first child `<Match>` whose `when` is truthy, or `fallback`.
+ * A chain of if/else-if/else expressed as markup instead of nested ternaries.
+ */
+export function Switch(props: SwitchProps): React.ReactElement | null;
+
+export interface MatchProps<T> {
+  when: T | Falsy;
+  children: React.ReactNode | ((value: Exclude<T, Falsy>) => React.ReactNode);
+}
+/** Only meaningful as a direct (or fragment-wrapped) child of `<Switch>`. */
+export function Match<T>(props: MatchProps<T>): null;
+
+// ---------------------------------------------------------------------------
+// Conditional - the original, all-in-one API. Fully supported; Show/For/
+// Switch/Match cover the same ground with real narrowing where Conditional
+// cannot offer it, because `when`/`each` here have to stay typed loosely
+// enough to cover all five of Conditional's modes in one prop bag.
+// ---------------------------------------------------------------------------
+
+export interface Comparison<T> {
+  value: T;
+  target: T;
+}
+export interface StringComparison {
+  value: unknown;
+  target: string;
+}
+export interface MatchComparison {
+  value: unknown;
+  pattern: string;
+}
+
+export interface ConditionalProps<T = unknown> {
+  when?: unknown;
+  each?: readonly T[] | null;
+  children?:
+    | React.ReactNode
+    | ((item: T, index: number, items: readonly T[]) => React.ReactNode);
+  fallback?: React.ReactNode;
+  /** Rendered when `each` is empty; falls back to `fallback` if omitted. */
+  empty?: React.ReactNode;
+  loading?: boolean;
+  /** Rendered while `loading` is true, taking priority over `fallback`. */
+  loadingFallback?: React.ReactNode;
+  error?: unknown;
+  /** Rendered instead of the default "Error: ..." message when `error` is set. */
+  errorFallback?: React.ReactNode | ((error: unknown) => React.ReactNode);
+  keyExtractor?: (item: T, index: number) => React.Key;
+  filter?: (item: T) => boolean;
+  sort?: (a: T, b: T) => number;
+  limit?: number;
+  reverse?: boolean;
+  /** Adds the `conditional-animated` class; define that class yourself. */
+  animate?: boolean;
+  /** Host element or component to wrap the rendered output in. @default React.Fragment */
+  wrapper?: React.ElementType;
+  debug?: boolean;
+  onRender?: (info: {
+    condition: boolean;
+    itemCount: number;
+    hasCondition: boolean;
+    hasIteration: boolean;
+  }) => void;
+  /** @deprecated Use `when={value > target}` instead - see `<Show>`. */
+  gt?: Comparison<number>;
+  /** @deprecated Use `when={value < target}` instead - see `<Show>`. */
+  lt?: Comparison<number>;
+  /** @deprecated Use `when={value === target}` instead - see `<Show>`. */
+  eq?: Comparison<unknown>;
+  /** @deprecated Use `when={value !== target}` instead - see `<Show>`. */
+  ne?: Comparison<unknown>;
+  /** @deprecated Use `when={String(value).includes(target)}` instead - see `<Show>`. */
+  includes?: StringComparison;
+  /** @deprecated Use `when={String(value).startsWith(target)}` instead - see `<Show>`. */
+  startsWith?: StringComparison;
+  /** @deprecated Use `when={String(value).endsWith(target)}` instead - see `<Show>`. */
+  endsWith?: StringComparison;
+  /** @deprecated Use `when={new RegExp(pattern).test(String(value))}` instead - see `<Show>`. */
+  match?: MatchComparison;
+  /** Value to match against child `<Case when={...}>` elements. */
+  switch?: unknown;
+}
+/**
+ * All-in-one conditional rendering / iteration / switch / if-else-if
+ * component. See `<Show>`, `<For>`, and `<Switch>`/`<Match>` for narrower,
+ * TypeScript-narrowing-friendly alternatives covering the same ground.
+ */
+export default function Conditional<T = unknown>(
+  props: ConditionalProps<T>
+): React.ReactElement | null;
+
+export interface CaseProps {
+  when?: unknown;
+  /** Renders when no sibling `<Case when={...}>` matched the `switch` value. */
+  default?: boolean;
+  children?: React.ReactNode;
+}
+/** Only meaningful as a direct (or fragment-wrapped) child of `<Conditional switch={...}>`. */
+export function Case(props: CaseProps): null;
+
+export interface BranchProps<T = unknown> {
+  when?: unknown;
+  each?: readonly T[] | null;
+  children?:
+    | React.ReactNode
+    | ((item: T, index: number, items: readonly T[]) => React.ReactNode);
+  filter?: (item: T) => boolean;
+  sort?: (a: T, b: T) => number;
+  limit?: number;
+  reverse?: boolean;
+  wrapper?: React.ElementType;
+  keyExtractor?: (item: T, index: number) => React.Key;
+  empty?: React.ReactNode;
+  fallback?: React.ReactNode;
+}
+/** Only meaningful as a direct (or fragment-wrapped) child of a bare `<Conditional>`. */
+export function If<T = unknown>(props: BranchProps<T>): null;
+/** Only meaningful as a direct (or fragment-wrapped) child of a bare `<Conditional>`. */
+export function ElseIf<T = unknown>(props: BranchProps<T>): null;
+/** Only meaningful as a direct (or fragment-wrapped) child of a bare `<Conditional>`. */
+export function Else<T = unknown>(props: Omit<BranchProps<T>, 'when'>): null;
+
+// ---------------------------------------------------------------------------
+// useConditionalHelpers
+// ---------------------------------------------------------------------------
+
+export interface ConditionalHelpers {
+  isEmpty(array: readonly unknown[] | null | undefined): { when: boolean };
+  isNotEmpty(array: readonly unknown[] | null | undefined): { when: boolean };
+  hasLength(array: readonly unknown[] | null | undefined, length: number): { when: boolean };
+  isEven(num: number): { when: boolean };
+  isOdd(num: number): { when: boolean };
+  sortBy<T>(field: keyof T, order?: 'asc' | 'desc'): (a: T, b: T) => number;
+  filterBy<T>(field: keyof T, value: T[keyof T]): (item: T) => boolean;
+  unique<T>(array: readonly T[] | null | undefined, key: keyof T | ((item: T) => unknown)): T[];
+}
+export function useConditionalHelpers(): ConditionalHelpers;

package/dist/index.js

@@ -21,12 +21,36 @@ Object.defineProperty(exports, "ElseIf", {
     return _ElseIf.default;
   }
 });
+Object.defineProperty(exports, "For", {
+  enumerable: true,
+  get: function () {
+    return _For.default;
+  }
+});
 Object.defineProperty(exports, "If", {
   enumerable: true,
   get: function () {
     return _If.default;
   }
 });
+Object.defineProperty(exports, "Match", {
+  enumerable: true,
+  get: function () {
+    return _Match.default;
+  }
+});
+Object.defineProperty(exports, "Show", {
+  enumerable: true,
+  get: function () {
+    return _Show.default;
+  }
+});
+Object.defineProperty(exports, "Switch", {
+  enumerable: true,
+  get: function () {
+    return _Switch.default;
+  }
+});
 exports.default = void 0;
 Object.defineProperty(exports, "useConditionalHelpers", {
   enumerable: true,
@@ -39,6 +63,10 @@ var _Case = _interopRequireDefault(require("./Case"));
 var _If = _interopRequireDefault(require("./If"));
 var _ElseIf = _interopRequireDefault(require("./ElseIf"));
 var _Else = _interopRequireDefault(require("./Else"));
+var _Show = _interopRequireDefault(require("./Show"));
+var _For = _interopRequireDefault(require("./For"));
+var _Switch = _interopRequireDefault(require("./Switch"));
+var _Match = _interopRequireDefault(require("./Match"));
 var _useConditionalHelpers = require("./useConditionalHelpers");
 function _interopRequireDefault(e) { return e && e.__esModule ? e : { default: e }; }
 var _default = exports.default = _Conditional.default;

package/dist/markers.js

@@ -3,10 +3,13 @@
 Object.defineProperty(exports, "__esModule", {
   value: true
 });
-exports.warnOnce = exports.markerKindOf = exports.createMarker = exports.IF = exports.ELSE_IF = exports.ELSE = exports.CASE = void 0;
-// Branch markers (`If`, `ElseIf`, `Else`, `Case`) are never rendered by React
-// when they are used correctly: `Conditional` reads their props and renders the
-// winning branch itself. They exist only so that JSX can express the shape.
+exports.warnOnce = exports.markerKindOf = exports.flattenBranches = exports.createMarker = exports.MATCH = exports.IF = exports.ELSE_IF = exports.ELSE = exports.CASE = void 0;
+var _react = _interopRequireDefault(require("react"));
+function _interopRequireDefault(e) { return e && e.__esModule ? e : { default: e }; }
+// Branch markers (`If`, `ElseIf`, `Else`, `Case`, `Match`) are never rendered
+// by React when they are used correctly: their parent (`Conditional` or
+// `Switch`) reads their props and renders the winning branch itself. They
+// exist only so that JSX can express the shape.
 //
 // Identifying them by reference (`child.type === If`) breaks as soon as two
 // copies of this package end up in node_modules, so each marker carries a
@@ -16,6 +19,7 @@ const IF = exports.IF = 'if';
 const ELSE_IF = exports.ELSE_IF = 'elseif';
 const ELSE = exports.ELSE = 'else';
 const CASE = exports.CASE = 'case';
+const MATCH = exports.MATCH = 'match';
 const TAG = '$$rtbgMarker';
 const warned = new Set();
 const warnOnce = message => {
@@ -24,12 +28,12 @@ const warnOnce = message => {
   console.warn(message);
 };
 exports.warnOnce = warnOnce;
-const createMarker = (name, kind) => {
-  // Rendering nothing is the safe default: a marker that slipped outside a
-  // `Conditional` must not leak the content it was meant to gate.
+const createMarker = (name, kind, parentName) => {
+  // Rendering nothing is the safe default: a marker that slipped outside its
+  // parent must not leak the content it was meant to gate.
   const Marker = () => {
     if (process.env.NODE_ENV !== 'production') {
-      warnOnce(`[react-ternary-be-gone] <${name}> only works as a child of <Conditional>. ` + 'It rendered nothing.');
+      warnOnce(`[react-ternary-be-gone] <${name}> only works as a child of <${parentName}>. ` + 'It rendered nothing.');
     }
     return null;
   };
@@ -39,4 +43,22 @@ const createMarker = (name, kind) => {
 };
 exports.createMarker = createMarker;
 const markerKindOf = element => element && element.type && element.type[TAG] || null;
-exports.markerKindOf = markerKindOf;
+
+// `React.Children.toArray` flattens arrays produced by `.map()`, but an
+// author-written `<>...</>` around a set of branches is itself a single
+// Fragment element in the tree - its contents need an explicit unwrap or
+// branch markers inside one are never seen by the scanner that looks for
+// them.
+exports.markerKindOf = markerKindOf;
+const flattenBranches = children => {
+  const result = [];
+  _react.default.Children.toArray(children).forEach(child => {
+    if (child && child.type === _react.default.Fragment) {
+      result.push(...flattenBranches(child.props.children));
+    } else {
+      result.push(child);
+    }
+  });
+  return result;
+};
+exports.flattenBranches = flattenBranches;

package/dist/shared.js

@@ -0,0 +1,35 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.renderIterableChildren = exports.processArray = void 0;
+var _react = _interopRequireDefault(require("react"));
+function _interopRequireDefault(e) { return e && e.__esModule ? e : { default: e }; }
+// Pure helper: apply filter/sort/reverse/limit to an `each` array without
+// mutating the caller's array (Array.prototype.sort/reverse mutate in place,
+// so every step works off a copy). Shared by `Conditional`'s `each` mode,
+// its If/ElseIf/Else branches, and `<For>`.
+const processArray = (array, {
+  filter,
+  sort,
+  reverse,
+  limit
+}) => {
+  if (!Array.isArray(array)) return [];
+  let result = [...array];
+  if (typeof filter === 'function') result = result.filter(filter);
+  if (typeof sort === 'function') result = result.sort(sort);
+  if (reverse) result = result.reverse();
+  if (typeof limit === 'number') result = result.slice(0, limit);
+  return result;
+};
+
+// Pure helper: render one React.Fragment per item, guarding the render-prop
+// call so static children (a plain element instead of a function) don't
+// crash when they reach an iteration path.
+exports.processArray = processArray;
+const renderIterableChildren = (items, children, keyExtractor) => items.map((item, index) => /*#__PURE__*/_react.default.createElement(_react.default.Fragment, {
+  key: keyExtractor ? keyExtractor(item, index) : index
+}, typeof children === 'function' ? children(item, index, items) : children));
+exports.renderIterableChildren = renderIterableChildren;

package/package.json

@@ -1,16 +1,18 @@
 {
   "name": "react-ternary-be-gone",
-  "version": "0.1.5",
+  "version": "0.2.0",
   "description": "A React component designed to simplify conditional rendering and list iteration, providing a more readable and maintainable alternative to ternary operators and verbose conditional logic.",
   "main": "dist/index.js",
+  "types": "dist/index.d.ts",
   "files": [
     "dist"
   ],
   "scripts": {
     "test": "vitest run",
     "test:watch": "vitest",
-    "build": "babel src --out-dir dist --out-file-extension .js",
-    "prepublishOnly": "npm test && npm run build"
+    "typecheck": "tsc -p test-types",
+    "build": "babel src --out-dir dist --out-file-extension .js && cp src/index.d.ts dist/index.d.ts",
+    "prepublishOnly": "npm test && npm run typecheck && npm run build"
   },
   "peerDependencies": {
     "react": ">=16.8.0"
@@ -43,10 +45,13 @@
     "@babel/preset-env": "^8.0.0",
     "@babel/preset-react": "^8.0.0",
     "@testing-library/react": "^16.3.3",
+    "@types/react": "^19.3.0",
+    "@types/react-dom": "^19.3.0",
     "@vitejs/plugin-react": "^5.0.0",
     "jsdom": "^30.1.1",
     "react": "^19.3.0",
     "react-dom": "^19.3.0",
+    "typescript": "^7.0.2",
     "vitest": "^5.0.1"
   }
 }