@object-ui/layout 17.2.0 → 17.5.0

package/README.md

@@ -17,9 +17,27 @@ pnpm add @object-ui/layout
 ```
 
 **Peer Dependencies:**
-- `react` >= 18.0.0
-- `react-dom` >= 18.0.0
-- `react-router-dom` >= 6.0.0
+- `react` ^18.0.0 || ^19.0.0
+- `react-dom` ^18.0.0 || ^19.0.0
+- `react-router-dom` ^6.0.0 || ^7.0.0
+
+## Registration
+
+Importing this package registers its component keys (`page-header`, `page:card`,
+`app-shell`, `responsive-grid`, `navigation-renderer`, `app-schema-renderer`) on
+the `ComponentRegistry` as a module load side effect, so the side-effect-only
+import is enough:
+
+```typescript
+import '@object-ui/layout';
+```
+
+That is a supported entry point, not an accident of the build: `package.json`
+declares the registering modules in `sideEffects`, which is what stops a bundler
+from tree-shaking a side-effect-only import away (objectui#3899 — the manifest
+used to say `"sideEffects": false`, and a bundler honouring it dropped the
+registration silently). `registerLayout()` is also exported for hosts that
+prefer to register explicitly.
 
 ## Components
 
@@ -119,22 +137,11 @@ All components accept `className` prop for Tailwind customization:
 
 ## API Reference
 
-For detailed API documentation, visit the [Object UI Documentation](https://www.objectui.org/docs/layout).
-
-<!-- release-metadata:v3.3.0 -->
-
-## Compatibility
-
-- **React:** 18.x or 19.x
-- **Node.js:** ≥ 18
-- **TypeScript:** ≥ 5.0 (strict mode)
-- **`@objectstack/spec`:** ^3.3.0
-- **`@objectstack/client`:** ^3.3.0
-- **Tailwind CSS:** ≥ 3.4 (for packages with UI)
+For detailed API documentation, visit the [Object UI Documentation](https://www.objectui.org/docs/layout/app-shell).
 
 ## Links
 
-- 📚 [Documentation](https://www.objectui.org/docs/layout)
+- 📚 [Documentation](https://www.objectui.org/docs/guide/layout)
 - 📦 [npm package](https://www.npmjs.com/package/@object-ui/layout)
 - 📝 [Changelog](./CHANGELOG.md)
 - 🐛 [Report an issue](https://github.com/objectstack-ai/objectui/issues)

package/dist/AppSchemaRenderer.d.ts

@@ -49,7 +49,9 @@ export interface AppSchemaRendererProps {
  * Responsibilities:
  * - Reads `name`, `title`, `description`, `logo`, `favicon` for branding
  * - Renders sidebar navigation from `navigation` or `areas[].navigation`
- * - Area switcher when multiple `areas` are defined
+ * - Area switcher when multiple areas are VISIBLE — area visibility is
+ *   derived from the items inside, not authored (objectui#3311): an area
+ *   whose items are all gated away is hidden and never auto-activated
  * - Mobile modes: `drawer` (sheet overlay, default), `bottom_nav` (fixed
  *   bottom bar), `hamburger` (collapsed sidebar)
  * - Evaluates `visible` expressions and `requiredPermissions` on every item

package/dist/NavigationRenderer.d.ts

@@ -1,5 +1,5 @@
 import { default as React } from 'react';
-import { NavigationItem } from '@object-ui/types';
+import { NavigationItem, KeyedI18nLabel } from '@object-ui/types';
 /**
  * Callback to evaluate a visibility expression.
  * Return `true` if the item should be visible.
@@ -141,14 +141,58 @@ export interface NavigationRendererProps {
 export declare function resolveIcon(name?: string): React.ComponentType<any>;
 /**
  * Resolve a NavigationItem label to a plain string.
- * Handles both plain strings and I18nLabel objects { key, defaultValue }.
- * When a `t` function is provided, I18nLabel objects are translated via i18next.
+ *
+ * Handles both plain strings and the KEYED i18n form
+ * `{ key, defaultValue?, params? }` — named `KeyedI18nLabel` in
+ * `@object-ui/types` since #4581, which is what this signature now states
+ * instead of a third inline copy of the same object literal. When a `t`
+ * function is provided the key is translated via i18next.
+ *
+ * "Keyed", not the spec's `I18nLabel`: that one is the INLINE LOCALE MAP
+ * (`{ en: 'Owner' }`) resolved against a BCP-47 locale, and the two answer
+ * wrongly for each other's input, silently (objectui#4167).
+ */
+export declare function resolveLabel(label: string | KeyedI18nLabel, t?: (key: string, options?: any) => string): string;
+/** Guard callbacks for {@link hasVisibleNavigationItems}. */
+export interface NavigationVisibilityOptions {
+    /** Evaluator for item `visible` expressions. Defaults to always-visible. */
+    evaluateVisibility?: VisibilityEvaluator;
+    /** Checker for item `requiredPermissions`. Defaults to always-permitted. */
+    checkPermission?: PermissionChecker;
+    /** Checker for `requiresObject` / `requiresService`. Defaults to pass. */
+    checkCapability?: CapabilityChecker;
+    /**
+     * Whether the host wires an `onAction` dispatcher. Without one, `action`
+     * items are not rendered at all (framework#4509 — a nav entry that looks
+     * clickable and silently does nothing is worse than an absent one), so
+     * they cannot carry an area's visibility either. Defaults to `false`,
+     * matching a renderer with no `onAction` prop.
+     */
+    hasActionHandler?: boolean;
+}
+/**
+ * Whether a navigation tree contains at least one item that would actually
+ * render under the given guards — the exact guards `NavigationItemRenderer`
+ * applies per item: the `visible` expression, `requiredPermissions`, the
+ * `requiresObject` / `requiresService` runtime-capability gates, and (for
+ * `action` items) the presence of an action dispatcher.
+ *
+ * Non-content nodes never count: a `separator` is a visual divider, and a
+ * `group` counts only through its children — a group whose children are all
+ * gated away contributes nothing a user can navigate to.
+ *
+ * This is the predicate behind DERIVED area visibility (objectui#3311).
+ * `@objectstack/spec` 17.0.0 retired the authorable area-level `visible` /
+ * `requiredPermissions` (`AREA_VISIBLE_RETIRED` /
+ * `AREA_REQUIRED_PERMISSIONS_RETIRED`): an area is a layout grouping, not an
+ * access boundary. What replaces those keys is not a new key but this
+ * derivation: an area is visible iff something inside it is. Because it is
+ * computed from the same guards that decide what renders, it can never
+ * disagree with the rendered navigation — and there is nothing for a
+ * metadata author to get wrong. An area with no items at all derives the
+ * same way (no visible item → hidden).
  */
-export declare function resolveLabel(label: string | {
-    key: string;
-    defaultValue?: string;
-    params?: Record<string, any>;
-}, t?: (key: string, options?: any) => string): string;
+export declare function hasVisibleNavigationItems(items: NavigationItem[], options?: NavigationVisibilityOptions): boolean;
 /**
  * Lightweight template-variable context for nav items that target a
  * specific record / org. The shell injects the signed-in user id and

package/dist/ResponsiveGrid.d.ts

@@ -1,28 +1,25 @@
 import { default as React } from 'react';
+import { BreakpointColumnMap, BreakpointOrderMap } from '@objectstack/spec/ui';
 /**
- * Spec-aligned breakpoint column map (mirrors @objectstack/spec BreakpointColumnMapSchema).
- * Maps breakpoint names to grid column counts (1-12).
- */
-export interface BreakpointColumnMap {
-    xs?: number;
-    sm?: number;
-    md?: number;
-    lg?: number;
-    xl?: number;
-    '2xl'?: number;
-}
-/**
- * Spec-aligned breakpoint order map (mirrors @objectstack/spec BreakpointOrderMapSchema).
- * Maps breakpoint names to display order numbers.
+ * Breakpoint column map (`BreakpointColumnMapSchema`) and breakpoint order map
+ * (`BreakpointOrderMapSchema`), both re-exported from `@objectstack/spec/ui`.
+ *
+ * These were hand copies until objectui#4167, each carrying the word "mirrors"
+ * — the doc-comment shape objectstack#4115 catalogues, where the claim is what
+ * the next agent reads as canonical and the code is what actually decides. rc.6
+ * publishes both names, and both copies happened to still be exact: six
+ * optional numbers keyed `xs`…`2xl`, on a `$strict` schema. "Still exact" is
+ * the argument FOR binding them, not against — the copies had nothing to
+ * protect, so the only thing they could do from here was drift, and a
+ * breakpoint the spec adds now arrives instead of silently not existing.
+ *
+ * `BreakpointOrderMap` has no read point in this package (`ResponsiveGrid`
+ * resolves columns only); it is published because `ResponsiveConfigSchema`
+ * pairs the two and an author configuring order needs the type. Bound rather
+ * than deleted for that reason — deleting a published type is a separate
+ * decision from stopping it being a fork.
  */
-export interface BreakpointOrderMap {
-    xs?: number;
-    sm?: number;
-    md?: number;
-    lg?: number;
-    xl?: number;
-    '2xl'?: number;
-}
+export type { BreakpointColumnMap, BreakpointOrderMap };
 export interface ResponsiveGridProps {
     /** Grid column map per breakpoint */
     columns?: BreakpointColumnMap;