@cratis/scene.blueprint.invoicing 0.0.0-stage → 4.71.0

package/index.ts

@@ -0,0 +1,14 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+export * from './packageName';
+export * from './templateProvenance';
+export * from './invoicingQueries';
+export * from './invoicingParts';
+export * from './invoicingScreenSet';
+export * from './templates';
+export * from './screens';
+export * from './navigation';
+export * from './manifest';
+export * from './blueprint';
+export * from './invoicingApplication';

package/invoicingApplication.ts

@@ -0,0 +1,28 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { UiProfile } from '@cratis/scene.model';
+import { ApplicationStructureIndex } from '@cratis/scene.engine';
+import { ApplicationDocument, CompositionOptions, defaultLayouts, previewProfile } from '@cratis/scene.blueprint.default';
+import { invoicingNavigation, invoicingStructure } from './navigation';
+import { invoicingScreens } from './screens';
+import { invoicingDialogTemplates, invoicingScreenTemplates } from './templates';
+
+/** The id of the sample-data pack a new application starts with. */
+export const invoicingDefaultSampleDataId = 'invoicing-en';
+
+/**
+ * The example application of the blueprint: the foundation's layouts, the Invoicing templates, the quick-create dialogs and their 5 screens, rendering against the
+ * foundation's packages with the default sample-data pack chosen. This is what a gallery previews and what the conformance fixture
+ * (`Samples/Invoicing/invoicing.play`) declares in Screenplay: the document, the structure and the navigation are the three things an application is made of.
+ */
+export function invoicingApplication(sampleData: string = invoicingDefaultSampleDataId): ApplicationDocument {
+    const profile: UiProfile = { ...previewProfile(undefined), name: 'Invoicing', sampleData: { activePack: sampleData, mappings: [], bindings: [] } };
+    return { layouts: defaultLayouts, screenTemplates: invoicingScreenTemplates, dialogTemplates: invoicingDialogTemplates, screens: invoicingScreens, uiProfiles: [profile] };
+}
+
+/** What a host composes the screens with: the application's logo, which the shell's topbar shows. */
+export const invoicingComposition: CompositionOptions = { logo: invoicingNavigation.application.logo };
+
+/** The structure and navigation the shell's regions show and the items' destinations resolve against. */
+export const invoicingNavigationModel = () => ({ structure: new ApplicationStructureIndex(invoicingStructure), navigation: invoicingNavigation });

package/invoicingParts.ts

@@ -0,0 +1,58 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import {
+    Behavior, BindingSourceKind, DialogTemplate, ExternalComponent, InteractionActionKind, InteractionTriggerKind, NavigateAction, OpenDialogAction, SceneElement, ScreenTemplate, TemplateMetadata, TemplateScope,
+} from '@cratis/scene.model';
+import { component, panel } from '@cratis/scene.blueprint.default';
+import { invoicingTemplateProvenance } from './templateProvenance';
+
+export { component, panel };
+
+/** The category of every template of this blueprint (spec Part B 1.2: `Business / <domain>`). */
+export const invoicingCategory = 'Business / Invoicing';
+
+/** The package-relative thumbnail of a template. */
+export const thumbnailOf = (templateName: string): string => `thumbnails/${templateName}.svg`;
+
+/** The metadata of a screen template of this blueprint: provenance, a type from the vocabulary, the category, a thumbnail and the levels it applies at. */
+export const invoicingMetadata = (name: string, type: 'Dashboard' | 'List' | 'Board' | 'Detail' | 'Form' | 'Dialog' | 'Workspace' | 'Calendar' | 'Timeline' | 'Inbox' | 'Profile' | 'Wizard', scopes: TemplateScope[]): TemplateMetadata =>
+    ({ ...invoicingTemplateProvenance, type, category: invoicingCategory, thumbnail: thumbnailOf(name), scopes });
+
+/** A button of the foundation: a verb, its emphasis, and the permission rule every action declares (spec Part B 1.5). */
+export const actionButton = (id: string, label: string, emphasis: 'primary' | 'secondary' | 'quiet' | 'danger', extra: Record<string, unknown> = {}, behaviors?: Behavior[]): ExternalComponent =>
+    ({ ...component(id, 'actionButton', { label, emphasis, permission: 'enabled', ...extra }), ...(behaviors ? { behaviors } : {}) });
+
+/** What pressing an element does: open the named dialog template over the page. */
+export const opensDialog = (dialogTemplate: string): Behavior[] =>
+    [{ bindings: [{ trigger: { kind: InteractionTriggerKind.Click }, actions: [{ kind: InteractionActionKind.OpenDialog, dialogTemplate } as OpenDialogAction] }] }];
+
+/** What pressing an element does: go to the named screen. */
+export const goesTo = (screen: string): Behavior[] =>
+    [{ bindings: [{ trigger: { kind: InteractionTriggerKind.Click }, actions: [{ kind: InteractionActionKind.Navigate, screen } as NavigateAction] }] }];
+
+/**
+ * What choosing a row of a list does: open the record page, handing it the chosen row's id. The list is single-selection, so choosing a row is
+ * opening it - the way a table of records works everywhere.
+ */
+export const opensRecordOnSelect = (listId: string, screen: string): Behavior[] => [{
+    bindings: [{
+        trigger: { kind: InteractionTriggerKind.Select },
+        actions: [{ kind: InteractionActionKind.Navigate, screen, arguments: [{ name: 'id', value: { kind: BindingSourceKind.ComponentProperty, componentId: listId, path: 'value' } }] } as NavigateAction],
+    }],
+}];
+
+/**
+ * What choosing a row of a list does: open the named dialog over the page - a side sheet with the row's detail, so the list stays where it was.
+ */
+export const opensDialogOnSelect = (dialogTemplate: string): Behavior[] =>
+    [{ bindings: [{ trigger: { kind: InteractionTriggerKind.Select }, actions: [{ kind: InteractionActionKind.OpenDialog, dialogTemplate } as OpenDialogAction] }] }];
+
+/** What a Cancel or Close control does: close the dialog it was opened from. */
+export const closesDialog = (): Behavior[] => [{ bindings: [{ trigger: { kind: InteractionTriggerKind.Click }, actions: [{ kind: InteractionActionKind.CloseDialog }] }] }];
+
+/** An element with the given behaviors attached. */
+export const withBehaviors = <T extends SceneElement>(element: T, behaviors: Behavior[]): T => ({ ...element, behaviors });
+
+export type InvoicingScreenTemplate = ScreenTemplate;
+export type InvoicingDialogTemplate = DialogTemplate;

package/invoicingQueries.ts

@@ -0,0 +1,58 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { BindingExpression, BindingSourceKind } from '@cratis/scene.model';
+
+/**
+ * A property taken from a query result - never a value. A invoicing template declares *where* its data comes from and the sample-data pack, or the real
+ * query, supplies the rows (spec SD1); `path` reaches into the result (`0.value` is the first row's `value`, an empty path is the whole result).
+ */
+export const fromQuery = (query: string, path = ''): BindingExpression => ({ kind: BindingSourceKind.QueryResult, query, path });
+
+/** The queries of the screens that are not a plain list. Each is a shape the sample-data pack supplies rows for. */
+export const InvoicingQuery = {
+    /** One row: the `locale` and `currency` the figures and dates are formatted in. */
+    Settings: 'InvoicingSettings',
+    Kpis: 'InvoicingKpis',
+    Aging: 'InvoicingAging',
+    InvoicedAndCollected: 'InvoicingInvoicedAndCollected',
+    Activity: 'InvoicingActivity',
+    DueDates: 'InvoicingDueDates',
+    DueColumns: 'InvoicingDueColumns',
+    FormErrors: 'InvoicingFormErrors',
+} as const;
+
+/** The entities a template is made for. */
+export enum InvoicingEntityKind {
+    Invoice = 'Invoice',
+    Payment = 'Payment',
+}
+
+/** The read model (and so the shape) the records of each entity are queried from. */
+export const invoicingEntityPlural: Record<InvoicingEntityKind, string> = {
+    [InvoicingEntityKind.Invoice]: 'Invoices',
+    [InvoicingEntityKind.Payment]: 'Payments',
+};
+
+/**
+ * The queries one entity's templates bind to, named from the entity so a template never spells one out: the records, the columns and filter fields of the
+ * list, its saved views and column choices, the selection, the sections of the quick form, and what the record page shows.
+ */
+export const invoicingQueriesOf = (entity: InvoicingEntityKind) => ({
+    rows: invoicingEntityPlural[entity],
+    columns: `${entity}Columns`,
+    filterFields: `${entity}FilterFields`,
+    views: `${entity}Views`,
+    columnChoices: `${entity}ColumnChoices`,
+    selection: `${entity}Selection`,
+    quickSections: `${entity}QuickSections`,
+    record: `${entity}Record`,
+    sections: `${entity}Sections`,
+    summary: `${entity}Summary`,
+    activity: `${entity}Activity`,
+    tabs: `${entity}Tabs`,
+});
+
+/** The locale and currency of the data, bound onto every component that formats a figure or a date. */
+export const localeOfData = { locale: fromQuery(InvoicingQuery.Settings, '0.locale') };
+export const currencyOfData = { ...localeOfData, currency: fromQuery(InvoicingQuery.Settings, '0.currency') };

package/invoicingScreenSet.ts

@@ -0,0 +1,22 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { BlueprintScreen } from '@cratis/scene.model';
+
+/** One ready-to-use screen: the qualified name that is also its place in the application (`invoicing.list.record` would be the `record` feature of `list`). */
+export interface InvoicingScreenDefinition extends BlueprintScreen {
+    template: string;
+    description: string;
+}
+
+/**
+ * The screens the blueprint brings, in navigation order. This one list is what the manifest's screen set, the `Screen` instances, the application structure
+ * and the navigation are all derived from, so they cannot disagree about which screens exist or where they sit.
+ */
+export const invoicingScreenDefinitions: InvoicingScreenDefinition[] = [
+    { name: 'invoicing.overview', title: 'Overview', template: 'InvoicingOverview', order: 0, description: 'What is owed, what is overdue and what came in this month.' },
+    { name: 'invoicing.list', title: 'Invoices', template: 'InvoicesList', order: 1, description: 'Every invoice with what is owed and its status.' },
+    { name: 'invoicing.record', title: 'Invoice', template: 'InvoicePage', parent: 'invoicing.list', description: 'One invoice: key facts, its lines, its payments and its activity.' },
+    { name: 'invoicing.payments', title: 'Payments', template: 'PaymentsList', order: 2, description: 'The payments received and the invoices they settled.' },
+    { name: 'invoicing.due', title: 'Due dates', template: 'InvoicingDueDates', order: 3, description: 'The day each invoice falls due, on a calendar.' },
+];

package/manifest.ts

@@ -0,0 +1,41 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { PackageKind, ScenePackage } from '@cratis/scene.model';
+import { invoicingBlueprintName } from './packageName';
+import { invoicingScreenDefinitions } from './invoicingScreenSet';
+import { invoicingDialogTemplates, invoicingScreenTemplates } from './templates';
+
+const description = 'Invoices for a finance team: a receivables overview, an invoice list, an invoice page with its lines and payments, the payments received and a due-date calendar.';
+
+/**
+ * This blueprint's declaration. A domain blueprint depends on the foundation set (`Cratis.Blueprint.Default`) and reuses its layouts, slots,
+ * components and themes - it ships none of its own - and adds what is specific to the domain: templates, a ready-to-use screen set, sample data
+ * and thumbnails. The package `version` is the blueprint's version: it is what a template reference pins and what "update available" compares.
+ */
+export const invoicingBlueprintManifest: ScenePackage = {
+    name: invoicingBlueprintName,
+    version: '1.0.0',
+    kind: PackageKind.Blueprint,
+    dependencies: [{ name: 'Cratis.Blueprint.Default', versionRange: '^1.0.0' }],
+    components: [],
+    layouts: [],
+    screenTemplates: invoicingScreenTemplates.map(template => template.name),
+    dialogTemplates: invoicingDialogTemplates.map(template => template.name),
+    themes: [],
+    displayName: 'Invoicing',
+    description,
+    module: '@cratis/scene.blueprint.invoicing',
+    license: 'MIT',
+    licenseUrl: 'https://github.com/Cratis/Scene/blob/main/LICENSE',
+    sampleData: [{ id: 'invoicing-en', title: 'Invoicing · English', locale: 'en-GB', path: 'sampleData/invoicing-en.json', description: 'English invoicing data: twelve invoices for six customers from draft to paid, one invoice\'s lines and payments, the payments received and the receivables figures.', columns: ['Invoice', 'Customer', 'Issued', 'Due', 'Amount'], statusColumn: 'Status', statuses: { good: ['Paid'], pending: ['Draft', 'Sent'], bad: ['Overdue', 'Void'] } }],
+    blueprint: {
+        domain: 'invoicing',
+        description,
+        thumbnail: 'thumbnails/invoicing.svg',
+        screenSet: invoicingScreenDefinitions.map(({ name, title, description: screenDescription, template, parent, order }) => ({
+            name, title, description: screenDescription, template, ...(parent === undefined ? {} : { parent }), ...(order === undefined ? {} : { order }),
+        })),
+        defaultSampleData: 'invoicing-en',
+    },
+};

package/navigation.ts

@@ -0,0 +1,54 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { ApplicationStructure, NavigationModel, NavigationRegionKind, NavigationRegionMode } from '@cratis/scene.model';
+import { invoicingScreenDefinitions } from './invoicingScreenSet';
+
+/** The module the blueprint's screens live in, and so the first segment of every screen's qualified name. */
+export const invoicingModule = 'invoicing';
+
+/**
+ * The application structure the screen set implies: one module, `invoicing`, a feature for each screen and the sub-features beneath it (`invoicing.record` is the
+ * `record` feature of the module). Derived from the screen names, so a screen added to the set is part of the structure without a second edit.
+ */
+export const invoicingStructure: ApplicationStructure = (() => {
+    interface Node { id: string; name: string; features: Node[]; slices: never[] }
+    const root: Node = { id: invoicingModule, name: 'Invoicing', features: [], slices: [] };
+    for (const screen of invoicingScreenDefinitions) {
+        let parent = root;
+        for (const id of screen.name.split('.').slice(1)) {
+            let node = parent.features.find(candidate => candidate.id === id);
+            if (!node) {
+                node = { id, name: screen.title, features: [], slices: [] };
+                parent.features.push(node);
+            }
+            parent = node;
+        }
+    }
+
+    return { modules: [{ id: root.id, name: root.name, features: root.features }] } as unknown as ApplicationStructure;
+})();
+
+/**
+ * The navigation of the application the blueprint is: the topbar names the module, and the module's sidebar - which overrides the application's - lists
+ * the places a team goes: Overview, Invoices, Payments, Due dates.
+ */
+export const invoicingNavigation: NavigationModel = {
+    application: {
+        logo: { image: '', title: 'Invoicing' },
+        regions: [{ region: NavigationRegionKind.Topbar, items: [{ id: 'invoicing', title: 'Invoicing', target: { module: invoicingModule } }] }],
+    },
+    modules: [{
+        module: invoicingModule,
+        regions: [{
+            region: NavigationRegionKind.Sidebar,
+            mode: NavigationRegionMode.Override,
+            items: [
+                { id: 'overview', title: 'Overview', target: { module: invoicingModule, feature: 'overview' } },
+                { id: 'list', title: 'Invoices', target: { module: invoicingModule, feature: 'list' } },
+                { id: 'payments', title: 'Payments', target: { module: invoicingModule, feature: 'payments' } },
+                { id: 'due', title: 'Due dates', target: { module: invoicingModule, feature: 'due' } },
+            ],
+        }],
+    }],
+};

package/package.json

@@ -1,6 +1,80 @@
 {
-  "name": "@cratis/scene.blueprint.invoicing",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+    "name": "@cratis/scene.blueprint.invoicing",
+    "version": "4.71.0",
+    "description": "Invoices for a finance team: a receivables overview, an invoice list, an invoice page with its lines and payments, the payments received and a due-date calendar.",
+    "keywords": [
+        "cratis",
+        "scene",
+        "react",
+        "ui",
+        "blueprint",
+        "invoicing"
+    ],
+    "author": "Cratis",
+    "license": "MIT",
+    "repository": {
+        "type": "git",
+        "url": "git+https://github.com/Cratis/Scene.git"
+    },
+    "publishConfig": {
+        "access": "public"
+    },
+    "files": [
+        "dist",
+        "sampleData",
+        "thumbnails",
+        "blueprintCatalog.json",
+        "**/*.ts",
+        "**/*.tsx",
+        "!**/for_*/**"
+    ],
+    "main": "dist/cjs/index.js",
+    "module": "dist/esm/index.js",
+    "types": "dist/esm/index.d.ts",
+    "exports": {
+        "./package.json": "./package.json",
+        ".": {
+            "types": "./dist/esm/index.d.ts",
+            "require": "./dist/cjs/index.js",
+            "import": "./dist/esm/index.js"
+        }
+    },
+    "scripts": {
+        "prepare": "yarn g:build",
+        "clean": "yarn g:clean",
+        "build": "yarn g:build",
+        "lint": "yarn g:lint",
+        "lint:ci": "yarn g:lint:ci",
+        "test": "yarn g:test",
+        "test:browser": "yarn g:test --config ./vitest.browser.config.mts",
+        "ci": "yarn g:ci",
+        "up": "yarn g:up"
+    },
+    "dependencies": {
+        "@cratis/scene.blueprint.default": "4.71.0",
+        "@cratis/scene.engine": "4.71.0",
+        "@cratis/scene.model": "4.71.0",
+        "@cratis/scene.react": "4.71.0"
+    },
+    "devDependencies": {
+        "@cratis/scene.blueprint.default": "4.71.0",
+        "@cratis/scene.engine": "4.71.0",
+        "@cratis/scene.model": "4.71.0",
+        "@cratis/scene.react": "4.71.0",
+        "@primereact/core": "11.2.0",
+        "@primereact/headless": "11.2.0",
+        "primeicons": "8.0.2",
+        "primereact": "11.2.0",
+        "react": "^19.3.0",
+        "react-dom": "^19.3.0"
+    },
+    "peerDependencies": {
+        "@cratis/components": "^4.1.1",
+        "@primereact/core": "^11.0.0",
+        "@primereact/headless": "^11.0.0",
+        "primeicons": "^8.0.0",
+        "primereact": "^11.0.0",
+        "react": "^19.0.0",
+        "react-dom": "^19.0.0"
+    }
 }

package/packageName.ts

@@ -0,0 +1,5 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+/** The name this blueprint is known by inside a `ui profile`; every component registry key is built from it. */
+export const invoicingBlueprintName = 'Cratis.Blueprint.Invoicing';