|
| 1 | +/** |
| 2 | + * ObjectUI |
| 3 | + * Copyright (c) 2024-present ObjectStack Inc. |
| 4 | + * |
| 5 | + * This source code is licensed under the MIT license found in the |
| 6 | + * LICENSE file in the root directory of this source tree. |
| 7 | + */ |
| 8 | + |
| 9 | +/** |
| 10 | + * The `page-header` alias declares only keys `@objectstack/spec` declares |
| 11 | + * (objectui#3226). |
| 12 | + * |
| 13 | + * The legacy kebab key `page-header` and the canonical protocol key |
| 14 | + * `page:header` (in `@object-ui/components`) render the same concept, but this |
| 15 | + * one used to DECLARE a different authorable key for the secondary line: |
| 16 | + * `description`, where the spec's `PageHeaderProps` — and therefore |
| 17 | + * `page:header` — declares `subtitle`. That is not a tolerated legacy spelling, |
| 18 | + * it is a second dialect published on the declaration surface: `inputs` is what |
| 19 | + * the designer offers as fields and what the framework's |
| 20 | + * `check:react-declaration-parity` diffs against the spec schemas, so an author |
| 21 | + * (especially an AI one) was being TOLD `description` was legal. Metadata that |
| 22 | + * took the offer renders a subtitle under `page-header` and silently loses it |
| 23 | + * under `page:header` — the same JSON, two results, which is the failure mode |
| 24 | + * one contract exists to prevent. |
| 25 | + * |
| 26 | + * The cross-check below is deliberately derived from the spec's own shape |
| 27 | + * rather than a hand-written allowlist: a future input added here that the spec |
| 28 | + * does not declare fails for the same reason `description` did, without anyone |
| 29 | + * having to remember this issue. |
| 30 | + * |
| 31 | + * SEQUENCING — read before "finishing the job". `PageHeader.tsx` still READS |
| 32 | + * `subtitle ?? description` at runtime, and the last test in this file pins |
| 33 | + * that on purpose. The alias exists precisely for out-of-repo consumer schemas, |
| 34 | + * so "no in-repo author writes `description`" (true, verified) says nothing |
| 35 | + * about whether anyone does; dropping the read today would delete an external |
| 36 | + * page's second line while its title kept rendering — the least reportable |
| 37 | + * failure there is. The read goes away together with the ADR-0087 D2 conversion |
| 38 | + * entry `page-header-subtitle-alias` (`description` → `subtitle` rewritten at |
| 39 | + * load time), which lives in the framework repo. Narrowing the DECLARATION did |
| 40 | + * not need to wait on it and changes no runtime behaviour; deleting the READ |
| 41 | + * does. When that conversion lands, delete the fallback AND the last test here |
| 42 | + * in one change. |
| 43 | + */ |
| 44 | + |
| 45 | +import { describe, it, expect, beforeAll } from 'vitest'; |
| 46 | +import { render, screen } from '@testing-library/react'; |
| 47 | +import { ComponentRegistry } from '@object-ui/core'; |
| 48 | +import { PageHeaderProps as SpecPageHeaderProps } from '@objectstack/spec/ui'; |
| 49 | + |
| 50 | +import { registerLayout, PageHeader } from '../index'; |
| 51 | + |
| 52 | +/** Authorable keys of the spec node this renderer serves. */ |
| 53 | +const specKeys = new Set(Object.keys(SpecPageHeaderProps.shape)); |
| 54 | + |
| 55 | +const declaredInputNames = (type: string, namespace?: string): string[] => { |
| 56 | + const config = ComponentRegistry.getConfig(type, namespace); |
| 57 | + if (!config) throw new Error(`"${namespace ? `${namespace}:${type}` : type}" is not registered`); |
| 58 | + return (config.inputs ?? []).map((input) => input.name); |
| 59 | +}; |
| 60 | + |
| 61 | +beforeAll(() => { |
| 62 | + registerLayout(); |
| 63 | +}); |
| 64 | + |
| 65 | +describe('the `page-header` registration declares the spec key, not a dialect', () => { |
| 66 | + it('is registered under the bare key and its namespace', () => { |
| 67 | + expect(ComponentRegistry.getConfig('page-header')).toBeTruthy(); |
| 68 | + expect(ComponentRegistry.getConfig('page-header', 'layout')).toBeTruthy(); |
| 69 | + }); |
| 70 | + |
| 71 | + // The one assertion this issue is about: whatever else changes, the |
| 72 | + // declaration surface must never advertise `description` again. |
| 73 | + it.each([ |
| 74 | + ['page-header', undefined], |
| 75 | + ['page-header', 'layout'], |
| 76 | + ])('does not advertise `description` on %s (namespace: %s)', (type, namespace) => { |
| 77 | + expect(declaredInputNames(type, namespace)).not.toContain('description'); |
| 78 | + }); |
| 79 | + |
| 80 | + it('declares `subtitle` — the spec key for the secondary line', () => { |
| 81 | + expect(declaredInputNames('page-header')).toContain('subtitle'); |
| 82 | + expect(specKeys.has('subtitle')).toBe(true); |
| 83 | + // …and the spec has no `description` at all, which is the whole reason the |
| 84 | + // old declaration was wrong rather than merely redundant. |
| 85 | + expect(specKeys.has('description')).toBe(false); |
| 86 | + }); |
| 87 | + |
| 88 | + it('declares nothing `@objectstack/spec` does not', () => { |
| 89 | + const offSpec = declaredInputNames('page-header').filter((name) => !specKeys.has(name)); |
| 90 | + expect(offSpec).toEqual([]); |
| 91 | + }); |
| 92 | +}); |
| 93 | + |
| 94 | +describe('the runtime `description` fallback stays until the conversion entry lands', () => { |
| 95 | + // NOT an endorsement of the alias — a guard on the ORDER. Removing this read |
| 96 | + // before `page-header-subtitle-alias` exists is the deletion route that was |
| 97 | + // considered and rejected: external schemas authored with `description` would |
| 98 | + // lose their subtitle silently. Delete this test in the same change that |
| 99 | + // deletes the fallback, once the conversion rewrites the key upstream. |
| 100 | + it('still renders a legacy `description` as the secondary line', () => { |
| 101 | + render(<PageHeader title="Customer Details" description="View and edit customer information" />); |
| 102 | + expect(screen.getByText('View and edit customer information')).toBeTruthy(); |
| 103 | + }); |
| 104 | + |
| 105 | + it('lets the spec key win when both are present', () => { |
| 106 | + render(<PageHeader title="Customer Details" subtitle="From the spec" description="From the alias" />); |
| 107 | + expect(screen.getByText('From the spec')).toBeTruthy(); |
| 108 | + expect(screen.queryByText('From the alias')).toBeNull(); |
| 109 | + }); |
| 110 | +}); |
0 commit comments