@happyvertical/smrt-planner 0.0.0-stage → 0.0.2

package/dist/recipes/help/descriptions.json

@@ -0,0 +1,373 @@
+{
+  "@happyvertical/smrt-commerce:Customer": {
+    "profileId": "Links this customer to their profile record, where their name and contact details are kept.",
+    "creditLimit": "The most this customer may owe you at one time. Leave it empty or at zero if you do not set limits.",
+    "paymentTerms": "How long the customer has to pay, written the way you would say it, for example \"Net 30\".",
+    "taxExempt": "Turn this on if you do not charge this customer sales tax.",
+    "taxId": "The customer's tax or VAT number, kept on file for tax-exempt sales.",
+    "defaultShippingAddress": "Where you usually send this customer's goods, so you do not retype it on every order.",
+    "defaultBillingAddress": "Where you send this customer's invoices.",
+    "status": "Whether this is a current customer, for example active or inactive.",
+    "customerType": "The kind of customer, for example an individual or a business.",
+    "notes": "Anything worth remembering about this customer."
+  },
+  "@happyvertical/smrt-commerce:Vendor": {
+    "profileId": "Links this vendor to their profile record, where their name and contact details are kept.",
+    "leadTimeDays": "How many days the vendor usually takes between your order and delivery.",
+    "minimumOrderAmount": "The smallest order the vendor will accept.",
+    "paymentTerms": "How long you have to pay this vendor, written the way you would say it, for example \"Net 30\".",
+    "currency": "The currency this vendor bills you in.",
+    "defaultContactEmail": "The email address you normally use to reach this vendor.",
+    "defaultContactPhone": "The phone number you normally use to reach this vendor.",
+    "status": "Whether you still buy from this vendor, for example active or inactive.",
+    "notes": "Anything worth remembering about this vendor.",
+    "payoutAddresses": "Where payments to this vendor should be sent."
+  },
+  "@happyvertical/smrt-commerce:Order": {
+    "status": "Where the order stands, for example draft, accepted or completed.",
+    "customerId": "The customer this order is for.",
+    "subtotal": "The order amount before tax.",
+    "taxAmount": "The tax charged on the order.",
+    "totalAmount": "What the customer pays in all, tax included.",
+    "currency": "The currency of the order's amounts.",
+    "issueDate": "The date the order was placed.",
+    "dueDate": "The date payment is expected. An order still open after this date counts as overdue.",
+    "expiryDate": "The last day the order's price or offer is good for.",
+    "reference": "Your own number or note for finding this order later, such as the customer's purchase order number.",
+    "notes": "Anything worth remembering about this order.",
+    "terms": "The conditions agreed with the customer, such as deposits, delivery or payment conditions.",
+    "channelId": "Where the order came from, for example your shop or a marketplace."
+  },
+  "@happyvertical/smrt-commerce:PurchaseOrder": {
+    "status": "Where the purchase stands, for example draft, accepted or completed.",
+    "vendorId": "The vendor you are buying from.",
+    "subtotal": "The order amount before tax.",
+    "taxAmount": "The tax charged on the order.",
+    "totalAmount": "What you pay in all, tax included.",
+    "currency": "The currency of the order's amounts.",
+    "issueDate": "The date you placed the order.",
+    "dueDate": "The date the goods or the payment are due.",
+    "expiryDate": "The last day the vendor's offer is good for.",
+    "reference": "Your own number or note for finding this order later, such as the vendor's quote number.",
+    "notes": "Anything worth remembering about this purchase.",
+    "terms": "The conditions agreed with the vendor, such as payment or delivery conditions.",
+    "channelId": "Where the order was placed, for example a vendor's website or a phone call."
+  },
+  "@happyvertical/smrt-products:Product": {
+    "name": "What you call the product, as customers will see it.",
+    "price": "What one costs, in dollars and cents.",
+    "description": "A few words on what the product is and who it is for."
+  },
+  "@happyvertical/smrt-products:ProductVariant": {
+    "productId": "The product this choice belongs to. Set for you when you save the product.",
+    "axisName": "What the product varies by, for example size or color.",
+    "allowedValues": "The values on offer for it, for example S, M and L."
+  },
+  "@happyvertical/smrt-products:Sku": {
+    "productId": "The product this item is a version of. Set for you when you save the product.",
+    "code": "The short code that identifies this exact size and color. Made for you from the product name.",
+    "attributes": "Which size and color this item is. Set for you from the grid."
+  },
+  "@happyvertical/smrt-inventory:StockLevel": {
+    "skuId": "The item being counted. Set for you when you save the product.",
+    "locationId": "Where it is kept. New stock goes to the main warehouse.",
+    "state": "Whether the count is available to sell. New stock starts as available.",
+    "qty": "How many you have on hand."
+  },
+  "@happyvertical/smrt-inventory:InventoryLocation": {
+    "code": "A short code for the place stock is kept, for example MAIN.",
+    "name": "What you call the place, for example Main warehouse.",
+    "kind": "What sort of place it is, for example a warehouse or a shop floor."
+  },
+  "@happyvertical/smrt-commerce:Estimate": {
+    "status": "Where the estimate stands, for example draft, sent, accepted or completed.",
+    "customerId": "The customer this estimate is for.",
+    "subtotal": "The estimate amount before tax.",
+    "taxAmount": "The tax charged on the estimate.",
+    "totalAmount": "What the customer pays in all, tax included.",
+    "currency": "The currency of the estimate's amounts.",
+    "issueDate": "The date the estimate was issued or starts.",
+    "dueDate": "The date payment is expected.",
+    "expiryDate": "The last day the estimate is good for, or the day it ends.",
+    "reference": "Your own number or note for finding this estimate later.",
+    "notes": "Anything worth remembering about this estimate.",
+    "terms": "The conditions agreed with the customer, such as deposits, delivery or payment conditions.",
+    "channelId": "Where the estimate came from, for example your shop or a marketplace."
+  },
+  "@happyvertical/smrt-commerce:WholesaleOrder": {
+    "status": "Where the wholesale order stands, for example draft, sent, accepted or completed.",
+    "customerId": "The customer this wholesale order is for.",
+    "subtotal": "The wholesale order amount before tax.",
+    "taxAmount": "The tax charged on the wholesale order.",
+    "totalAmount": "What the customer pays in all, tax included.",
+    "currency": "The currency of the wholesale order's amounts.",
+    "issueDate": "The date the wholesale order was issued or starts.",
+    "dueDate": "The date payment is expected.",
+    "expiryDate": "The last day the wholesale order is good for, or the day it ends.",
+    "reference": "Your own number or note for finding this wholesale order later.",
+    "notes": "Anything worth remembering about this wholesale order.",
+    "terms": "The conditions agreed with the customer, such as deposits, delivery or payment conditions.",
+    "channelId": "Where the wholesale order came from, for example your shop or a marketplace."
+  },
+  "@happyvertical/smrt-commerce:Agreement": {
+    "status": "Where the agreement stands, for example draft, sent, accepted or completed.",
+    "customerId": "The customer this agreement is for.",
+    "subtotal": "The agreement amount before tax.",
+    "taxAmount": "The tax charged on the agreement.",
+    "totalAmount": "What the customer pays in all, tax included.",
+    "currency": "The currency of the agreement's amounts.",
+    "issueDate": "The date the agreement was issued or starts.",
+    "dueDate": "The date payment is expected.",
+    "expiryDate": "The last day the agreement is good for, or the day it ends.",
+    "reference": "Your own number or note for finding this agreement later.",
+    "notes": "Anything worth remembering about this agreement.",
+    "terms": "The conditions agreed with the customer, such as deposits, delivery or payment conditions.",
+    "channelId": "Where the agreement came from, for example your shop or a marketplace."
+  },
+  "@happyvertical/smrt-commerce:Lease": {
+    "status": "Where the lease stands, for example draft, sent, accepted or completed.",
+    "customerId": "The customer this lease is for.",
+    "subtotal": "The lease amount before tax.",
+    "taxAmount": "The tax charged on the lease.",
+    "totalAmount": "What the customer pays in all, tax included.",
+    "currency": "The currency of the lease's amounts.",
+    "issueDate": "The date the lease was issued or starts.",
+    "dueDate": "The date payment is expected.",
+    "expiryDate": "The last day the lease is good for, or the day it ends.",
+    "reference": "Your own number or note for finding this lease later.",
+    "notes": "Anything worth remembering about this lease.",
+    "terms": "The conditions agreed with the customer, such as deposits, delivery or payment conditions.",
+    "channelId": "Where the lease came from, for example your shop or a marketplace."
+  },
+  "@happyvertical/smrt-commerce:LicenseSale": {
+    "status": "Where the licence sale stands, for example draft, sent, accepted or completed.",
+    "customerId": "The customer this licence sale is for.",
+    "subtotal": "The licence sale amount before tax.",
+    "taxAmount": "The tax charged on the licence sale.",
+    "totalAmount": "What the customer pays in all, tax included.",
+    "currency": "The currency of the licence sale's amounts.",
+    "issueDate": "The date the licence sale was issued or starts.",
+    "dueDate": "The date payment is expected.",
+    "expiryDate": "The last day the licence sale is good for, or the day it ends.",
+    "reference": "Your own number or note for finding this licence sale later.",
+    "notes": "Anything worth remembering about this licence sale.",
+    "terms": "The conditions agreed with the customer, such as deposits, delivery or payment conditions.",
+    "channelId": "Where the licence sale came from, for example your shop or a marketplace."
+  },
+  "@happyvertical/smrt-commerce:Contract": {
+    "status": "Where the contract stands, for example draft, sent, accepted or completed.",
+    "customerId": "The customer this contract is for.",
+    "subtotal": "The contract amount before tax.",
+    "taxAmount": "The tax charged on the contract.",
+    "totalAmount": "What the customer pays in all, tax included.",
+    "currency": "The currency of the contract's amounts.",
+    "issueDate": "The date the contract was issued or starts.",
+    "dueDate": "The date payment is expected.",
+    "expiryDate": "The last day the contract is good for, or the day it ends.",
+    "reference": "Your own number or note for finding this contract later.",
+    "notes": "Anything worth remembering about this contract.",
+    "terms": "The conditions agreed with the customer, such as deposits, delivery or payment conditions.",
+    "channelId": "Where the contract came from, for example your shop or a marketplace.",
+    "contractType": "The kind of contract: order, estimate, lease, agreement and so on.",
+    "vendorId": "The vendor on the other side, for contracts you buy."
+  },
+  "@happyvertical/smrt-commerce:ContractLineItem": {
+    "contractId": "The order, quote or agreement this line belongs to.",
+    "description": "What is being sold or bought on this line.",
+    "quantity": "How many.",
+    "unitPrice": "The price of one, before tax.",
+    "taxRate": "The tax rate for this line, as a percentage (5 means 5%).",
+    "amount": "The line total.",
+    "productId": "The product this line is for, if it is one you list."
+  },
+  "@happyvertical/smrt-inventory:StockMovement": {
+    "skuId": "The item that moved.",
+    "locationId": "The place it moved at.",
+    "fromState": "What it was before, for example available or damaged.",
+    "toState": "What it became.",
+    "qty": "How many moved.",
+    "reasonCode": "Why it moved, for example adjustment, sale or return.",
+    "note": "Anything worth remembering about this movement.",
+    "occurredAt": "When it happened."
+  },
+  "@happyvertical/smrt-commerce:Invoice": {
+    "customerId": "The customer being billed.",
+    "contractId": "The order or agreement this invoice bills for, if any.",
+    "invoiceNumber": "The number printed on the invoice.",
+    "issueDate": "The date the invoice was issued.",
+    "dueDate": "The date payment is expected.",
+    "paidDate": "The date it was paid in full.",
+    "subtotal": "The amount before tax.",
+    "taxAmount": "The tax charged.",
+    "totalAmount": "What the customer owes in all, tax included.",
+    "amountPaid": "How much of the total has been paid so far.",
+    "currency": "The currency of the invoice.",
+    "status": "Where the invoice stands: draft, sent, viewed, paid, overdue or cancelled.",
+    "notes": "Private notes, not shown to the customer.",
+    "customerNotes": "A message shown to the customer on the invoice.",
+    "terms": "The payment conditions, such as Net 30."
+  },
+  "@happyvertical/smrt-commerce:InvoiceLineItem": {
+    "invoiceId": "The invoice this line belongs to.",
+    "description": "What is being billed on this line.",
+    "quantity": "How many.",
+    "unitPrice": "The price of one, before tax.",
+    "taxRate": "The tax rate for this line, as a percentage (5 means 5%).",
+    "amount": "The line total."
+  },
+  "@happyvertical/smrt-commerce:Payment": {
+    "contractId": "The order or agreement this payment is for, if any.",
+    "customerId": "The customer who paid.",
+    "amount": "How much was paid.",
+    "currency": "The currency of the payment.",
+    "method": "How it was paid: cash, check, card, bank transfer or other.",
+    "status": "Whether the payment is pending, completed, failed or refunded.",
+    "reference": "Your own note, such as a check number.",
+    "paidAt": "When the money was received.",
+    "notes": "Anything worth remembering about this payment."
+  },
+  "@happyvertical/smrt-commerce:PaymentAllocation": {
+    "paymentId": "The payment being applied.",
+    "invoiceId": "The invoice it settles.",
+    "amount": "How much of the payment goes to this invoice.",
+    "allocatedAt": "When it was applied.",
+    "notes": "Anything worth remembering about this allocation."
+  },
+  "@happyvertical/smrt-commerce:Fulfillment": {
+    "contractId": "The order being fulfilled.",
+    "fulfillmentType": "How it gets to the customer: shipment, delivery, pickup, digital or service.",
+    "status": "Where it stands: pending, processing, shipped, delivered or cancelled.",
+    "trackingNumber": "The carrier's tracking number.",
+    "carrier": "The company carrying it.",
+    "shippedAt": "When it left you.",
+    "deliveredAt": "When it arrived.",
+    "notes": "Anything worth remembering about this shipment."
+  },
+  "@happyvertical/smrt-commerce:FulfillmentLineItem": {
+    "fulfillmentId": "The shipment this line belongs to.",
+    "contractLineItemId": "The order line being sent.",
+    "quantityFulfilled": "How many of that line are in this shipment."
+  },
+  "@happyvertical/smrt-ledgers:Account": {
+    "number": "The account number in your chart of accounts.",
+    "name": "What the account is called.",
+    "description": "What the account is used for.",
+    "type": "asset, liability, equity, revenue or expense.",
+    "active": "Turn this off to stop using the account without deleting it."
+  },
+  "@happyvertical/smrt-ledgers:Journal": {
+    "number": "The journal's reference number.",
+    "date": "The date of the transaction.",
+    "description": "What the transaction was.",
+    "status": "draft while you work on it, posted once final, or voided.",
+    "postedAt": "When it was posted."
+  },
+  "@happyvertical/smrt-ledgers:JournalEntry": {
+    "journalId": "The journal this entry belongs to.",
+    "accountId": "The account this entry changes.",
+    "debit": "The amount debited. Leave zero on a credit.",
+    "credit": "The amount credited. Leave zero on a debit.",
+    "currency": "The currency of the amounts.",
+    "memo": "A note on this entry."
+  },
+  "@happyvertical/smrt-projects:Project": {
+    "title": "The project's name.",
+    "description": "What the project is about.",
+    "owner": "Who owns or runs the project.",
+    "url": "A link to the project elsewhere."
+  },
+  "@happyvertical/smrt-projects:Issue": {
+    "projectId": "The project this issue belongs to.",
+    "title": "A short summary of the issue.",
+    "body": "The full description.",
+    "state": "open or closed.",
+    "author": "Who raised the issue.",
+    "labels": "The labels attached to the issue.",
+    "assignees": "The people working on it."
+  },
+  "@happyvertical/smrt-projects:Label": {
+    "projectId": "The project this label belongs to.",
+    "name": "The label's name, for example bug.",
+    "color": "The label's colour.",
+    "description": "What the label means."
+  },
+  "@happyvertical/smrt-projects:Comment": {
+    "issueId": "The issue this comment is on.",
+    "body": "The comment text.",
+    "author": "Who wrote it."
+  },
+  "@happyvertical/smrt-events:Event": {
+    "name": "What the event is called.",
+    "seriesId": "The series this event is part of, if any.",
+    "typeId": "The kind of event.",
+    "placeId": "Where it takes place.",
+    "description": "What the event is about.",
+    "startDate": "When it starts.",
+    "endDate": "When it ends.",
+    "allDay": "Turn this on for an event that lasts all day.",
+    "status": "scheduled, in progress, completed, cancelled or postponed."
+  },
+  "@happyvertical/smrt-events:EventType": {
+    "name": "What this kind of event is called, for example workshop.",
+    "description": "What this kind of event is for."
+  },
+  "@happyvertical/smrt-events:EventSeries": {
+    "name": "What the series is called.",
+    "typeId": "The kind of event in this series.",
+    "organizerId": "Who runs the series.",
+    "description": "What the series is about.",
+    "startDate": "When the series begins.",
+    "endDate": "When the series ends.",
+    "recurrence": "How often it repeats."
+  },
+  "@happyvertical/smrt-events:EventParticipant": {
+    "eventId": "The event the person takes part in.",
+    "profileId": "The person taking part.",
+    "role": "What they do there, for example speaker or attendee."
+  },
+  "@happyvertical/smrt-sales:Lead": {
+    "name": "What you call this lead.",
+    "contactName": "The person to talk to.",
+    "email": "Their email address.",
+    "phone": "Their phone number.",
+    "organizationName": "The company they are with.",
+    "ownerRepId": "The sales representative who owns this lead.",
+    "status": "Where the lead stands, for example new or qualified."
+  },
+  "@happyvertical/smrt-sales:Opportunity": {
+    "name": "What you call this deal.",
+    "leadId": "The lead it came from.",
+    "ownerRepId": "The sales representative who owns this deal.",
+    "pipelineId": "The pipeline it moves through.",
+    "stageId": "The stage it is at now.",
+    "expectedValueCents": "What you expect the deal to be worth, in cents.",
+    "currency": "The currency of that value.",
+    "probability": "How likely it is to close, as a decimal (0.5 is 50%).",
+    "expectedCloseAt": "When you expect it to close.",
+    "status": "open, won or lost."
+  },
+  "@happyvertical/smrt-sales:PipelineDefinition": {
+    "key": "A short code for the pipeline.",
+    "name": "What the pipeline is called.",
+    "isDefault": "Turn this on to use it for new deals.",
+    "status": "Whether the pipeline is in use.",
+    "metadata": "Extra details kept with the pipeline."
+  },
+  "@happyvertical/smrt-sales:PipelineStage": {
+    "pipelineId": "The pipeline this stage belongs to.",
+    "key": "A short code for the stage.",
+    "name": "What the stage is called.",
+    "sortOrder": "Where it comes in the pipeline.",
+    "probability": "How likely a deal at this stage is to close, as a decimal.",
+    "isWon": "Turn this on for the stage that means the deal is won.",
+    "isLost": "Turn this on for the stage that means the deal is lost."
+  },
+  "@happyvertical/smrt-sales:SalesActivity": {
+    "subjectKind": "What the activity is about: a lead or an opportunity.",
+    "subjectId": "The lead or opportunity it is about.",
+    "activityKind": "The kind of activity, for example call, note or email.",
+    "summary": "What happened or what needs doing.",
+    "dueAt": "When it is due.",
+    "completedAt": "When it was done."
+  }
+}

package/dist/recipes/help.d.ts

@@ -0,0 +1,121 @@
+/**
+ * Recipe help: the `help` contract of happyvertical/smrt#3591 and the one
+ * renderer that follows an app's options. Everything the contract needs lives
+ * here and imports nothing from the planner, so the module can be swapped for
+ * the core helper once #3591 is published, and `help.ts` deleted.
+ *
+ * Contract. A recipe entry carries `help: { markdown, fieldRefs }`. The
+ * Markdown is user-facing prose with an overview and tasks. A step names a
+ * field as `{field:name}` or `{field:Model.name}`, and a Markdown block (a
+ * heading, a paragraph or a list item) containing a reference is tied to that
+ * field. Field descriptions come from `@field({ description })` and are passed
+ * in with the models.
+ *
+ * Rendering. {@link renderHelp} replaces each reference with the field's
+ * effective label, drops the blocks tied to a field the app does not show
+ * (hidden, advanced or unknown) and builds the glossary from the effective
+ * label and help, falling back to the description. The output is an AST, never
+ * HTML, so no raw markup from content can reach the page: the host renders the
+ * nodes as ordinary elements. Only a small subset of Markdown is understood:
+ * `##`/`###`/`####` headings, paragraphs, flat `-`/`*`/`1.` lists, and
+ * `**bold**`, `*italic*` and `` `code` `` inline. Anything else is plain text.
+ */
+/** What a recipe entry carries: the Markdown and every field it refers to. */
+export interface RecipeHelp {
+    markdown: string;
+    /** Distinct `{field:...}` targets as written (`status`, `Order.status`), sorted. */
+    fieldRefs: string[];
+}
+export type Inline = {
+    type: 'text';
+    text: string;
+} | {
+    type: 'code';
+    text: string;
+} | {
+    type: 'strong';
+    children: Inline[];
+} | {
+    type: 'em';
+    children: Inline[];
+}
+/** Present only before resolution; {@link renderHelp} replaces it. */
+ | {
+    type: 'field';
+    ref: string;
+};
+export interface HelpHeading {
+    type: 'heading';
+    level: 2 | 3 | 4;
+    inlines: Inline[];
+}
+export interface HelpParagraph {
+    type: 'paragraph';
+    inlines: Inline[];
+}
+export interface HelpItem {
+    inlines: Inline[];
+}
+export interface HelpList {
+    type: 'list';
+    ordered: boolean;
+    items: HelpItem[];
+}
+export type HelpBlock = HelpHeading | HelpParagraph | HelpList;
+/** Parse the supported Markdown subset into blocks. */
+export declare function parseHelp(markdown: string): HelpBlock[];
+/** Every distinct field reference in the Markdown, as written, sorted. */
+export declare function extractFieldRefs(markdown: string): string[];
+/** Build a contract entry from Markdown, deriving `fieldRefs`. */
+export declare function createRecipeHelp(markdown: string): RecipeHelp;
+/** A field as the app's options leave it: smrt-fields vocabulary. */
+export interface HelpField {
+    name: string;
+    /** Effective label. */
+    label: string;
+    /** Effective help; empty or absent falls back to the description. */
+    help?: string | null;
+    /** Only `basic` fields are shown. `hidden` and `advanced` are not. */
+    visibility: 'basic' | 'advanced' | 'hidden';
+}
+export interface HelpModel {
+    /** Qualified name, `@scope/pkg:Class`. */
+    id: string;
+    /** Class name, what `{field:Model.name}` uses. */
+    name: string;
+    /** In display order. */
+    fields: readonly HelpField[];
+    /** Field descriptions (`@field({ description })`), keyed by field name. */
+    descriptions?: Readonly<Record<string, string>>;
+    /**
+     * `false` when no list or form shows the model (a recipe with no menu
+     * entry): its fields still resolve in the prose, but get no glossary entry.
+     */
+    glossary?: boolean;
+}
+export interface GlossaryEntry {
+    model: string;
+    name: string;
+    label: string;
+    text: string;
+}
+export interface RenderedHelp {
+    blocks: HelpBlock[];
+    glossary: GlossaryEntry[];
+}
+/** Find a reference's field: `name` in the first model declaring it, or `Model.name`. */
+export declare function findField(ref: string, models: readonly HelpModel[]): {
+    model: HelpModel;
+    field: HelpField;
+} | undefined;
+/**
+ * Problems that should fail a build: references to fields the recipe's models
+ * do not declare, and a `fieldRefs` list that disagrees with the Markdown.
+ */
+export declare function validateHelp(help: RecipeHelp, models: readonly HelpModel[]): string[];
+/** Resolve the Markdown against the app's options. */
+export declare function resolveHelp(help: RecipeHelp, models: readonly HelpModel[]): HelpBlock[];
+/** One entry per shown field: effective label, then effective help or description. */
+export declare function buildGlossary(models: readonly HelpModel[]): GlossaryEntry[];
+/** The whole renderer: resolved blocks plus the field glossary. */
+export declare function renderHelp(help: RecipeHelp, models: readonly HelpModel[]): RenderedHelp;