@salesforce/afv-skills 1.13.0 → 1.15.0

package/skills/using-mobile-native-capabilities/references/nfc.md

@@ -0,0 +1,181 @@
+# NFC Service Grounding Context
+
+The following content provides grounding information for generating a Salesforce LWC that leverages NFC facilities on mobile devices. Specifically, this context will cover the API types and methods available to leverage the NFC API of the mobile device, within the LWC.
+
+## NFC Service API
+
+```typescript
+/*
+ * Copyright (c) 2024, Salesforce, Inc.
+ * All rights reserved.
+ * For full license text, see the LICENSE.txt file
+ */
+
+import { BaseCapability } from '../BaseCapability.js';
+
+/**
+ * Use this factory function to get an instance of {@linkcode NfcService}.
+ * @returns An instance of {@linkcode NfcService}.
+ */
+export function getNfcService(): NfcService;
+
+/**
+ * Interact with NFC tags from a Lightning web component.
+ * @see {@link https://developer.salesforce.com/docs/platform/lwc/guide/reference-lightning-nfcservice.html|NFCService API}
+ */
+export interface NfcService extends BaseCapability {
+  /**
+   * Reads an NFC tag and returns the data read from it.
+   * @param options An {@linkcode NFCServiceOptions} object to configure the {@linkcode NfcService} request.
+   * @returns A Promise object that resolves to an array containing a single {@linkcode NFCMessage} object.
+   */
+  read(options?: NFCServiceOptions): Promise<NFCMessage[]>;
+
+  /**
+   * Erase the contents of an NFC tag.
+   * @param options An {@linkcode NFCServiceOptions} object to configure the {@linkcode NfcService} request.
+   * @returns If successful, the OS returns a Promise object that resolves to null.
+   */
+  erase(options?: NFCServiceOptions): Promise<null>;
+
+  /**
+   * Write text to an NFC tag.
+   * @param payloads An array of {@linkcode NFCRecord} objects containing the raw bytes to be written.
+   * @param options An {@linkcode NFCServiceOptions} object to configure the {@linkcode NfcService} request.
+   * @returns If successful, the OS returns a Promise object that resolves to null.
+   */
+  write(payloads: NFCRecord[], options?: NFCServiceOptions): Promise<null>;
+
+  /**
+   * Given a text payload, this function creates a properly formatted {@linkcode NFCRecord} to be written to an NFC tag.
+   * @param payload A {@link TextPayload} object, which contains the text to be converted to an NFC record.
+   * @returns A Promise object that resolves to an {@linkcode NFCRecord} object.
+   */
+  createTextRecord(payload: TextPayload): Promise<NFCRecord>;
+
+  /**
+   * Given a URI string payload, this function creates a properly formatted {@linkcode NFCRecord} to be written to an NFC tag.
+   * @param payload The URI to be converted to an NFC record.
+   * @returns A Promise object that resolves to an {@linkcode NFCRecord} object.
+   */
+  createUriRecord(payload: string): Promise<NFCRecord>;
+}
+
+/**
+ * An object returned by an NFC read() operation.
+ */
+export interface NFCMessage {
+  /**
+   * The size, in number of bytes, of the data received by the read() operation.
+   */
+  totalByteLength: number;
+
+  /**
+   * An array containing a single {@linkcode NFCMessageRecord} object, which in turn contains the payload from the NFC tag.
+   */
+  records: NFCMessageRecord[];
+}
+
+/**
+ * An object within an {@linkcode NFCMessage} object, containing the payload read from an NFC tag.
+ */
+export interface NFCMessageRecord {
+  /**
+   * Contains the parsed values of the raw data read from the NFC tag. The parsing operation
+   * only occurs if the value of the typeNameFormat property on the {@linkcode NFCRecord} object is "WELLKNOWN".
+   * Otherwise, this property’s value is null.
+   */
+  parsed: NFCRecord;
+
+  /**
+   * Contains the raw base64 data string read from the NFC tag.
+   */
+  raw: NFCRecord;
+}
+
+/**
+ * An object containing one record of data from an NFC tag scan.
+ */
+export interface NFCRecord {
+  /**
+   * The Type Name Format field of the payload, as defined by the NDEF specification.
+   */
+  typeNameFormat: TypeNameFormat;
+
+  /**
+   * The type of the payload, as defined by the NDEF specification.
+   */
+  type: string;
+
+  /**
+   * The identifier of the payload, as defined by the NDEF specification, or an empty string if no identifier data was present in the tag.
+   */
+  identifier: string;
+
+  /**
+   * The content of the record, encoded in base64 format.
+   */
+  payload: string;
+}
+
+/**
+ * An object containing raw text input, to be converted into an {@linkcode NFCRecord}.
+ */
+export interface TextPayload {
+  /**
+   * The raw text payload to be converted.
+   */
+  text: string;
+
+  /**
+   * The ISO 639-1 language ID of the text.
+   */
+  langId: string;
+}
+
+/**
+ * The following constants are available as properties on an instance of {@linkcode NfcService}. The constants enumerate the accepted values for the associated properties.
+ */
+export type TypeNameFormat = 'ABSOLUTE_URI' | 'EMPTY' | 'EXTERNAL' | 'MEDIA' | 'WELLKNOWN' | 'UNCHANGED' | 'UNKNOWN';
+
+/**
+ * An object containing configuration details for an NFC interaction.
+ */
+export interface NFCServiceOptions {
+  /**
+   * Optional. Provides instructions to display in the user interface. Defaults to no text.
+   */
+  instructionText?: string;
+
+  /**
+   * Optional. Provides a message to display in the user interface when an NFC operation is successfully completed. Defaults to no text.
+   */
+  successText?: string;
+}
+
+/**
+ * An object representing an error that occurred when accessing {@linkcode NfcService} features.
+ */
+export interface NFCServiceFailure {
+  /**
+   * A value representing the reason for an error. See {@linkcode NFCServiceFailureCode} for the list of possible values.
+   */
+  code: NFCServiceFailureCode;
+
+  /**
+   * A string value describing the reason for the failure. This value is suitable for use in user interface messages. The message is provided in English and isn’t localized.
+   */
+  message: string;
+}
+
+/**
+ * Correlates with the code property on the {@linkcode NFCServiceFailure} object.
+ */
+export type NFCServiceFailureCode =
+  | 'USER_DISMISSED' // The user dismissed the scanner.
+  | 'NFC_NOT_SUPPORTED' // The device doesn’t support NFC capabilities.
+  | 'NFC_NOT_ENABLED' // The device NFC feature is turned off.
+  | 'TAG_EMPTY' // The NFC tag contains no data to be read.
+  | 'SERVICE_NOT_ENABLED' // NFCService is not enabled and cannot be used.
+  | 'UNKNOWN_REASON'; // An error occurred in the native code that isn’t related to permissions or hardware issues. More information is provided in the NFCServiceFailure message.
+```

package/skills/using-mobile-native-capabilities/references/payments.md

@@ -0,0 +1,95 @@
+# Payments Service Grounding Context
+
+The following content provides grounding information for generating a Salesforce LWC that leverages payments facilities on mobile devices. Specifically, this context will cover the API types and methods available to leverage the payments API of the mobile device, within the LWC.
+
+## Payments Service API
+
+```typescript
+/*
+ * Copyright (c) 2024, Salesforce, Inc.
+ * All rights reserved.
+ * For full license text, see the LICENSE.txt file
+ */
+
+import { BaseCapability } from '../BaseCapability.js';
+
+/**
+ * Use this factory function to get an instance of {@linkcode PaymentsService}.
+ * @returns An instance of {@linkcode PaymentsService}.
+ */
+export function getPaymentsService(): PaymentsService;
+
+/**
+ * PaymentsService is a Nimbus plugin that allows JavaScript code in a Lightning web component to call functions that launches Stripe's Tap to Pay capabilities.
+ */
+export interface PaymentsService extends BaseCapability {
+  /**
+   * Process payment.
+   * @param options The customization options.
+   * @returns A Promise object that resolves to {@linkcode CollectPaymentResult} object.
+   */
+  collectPayment(options: CollectPaymentOptions): Promise<CollectPaymentResult>;
+
+  /**
+   * Get the supported payment methods on this device
+   * @param options The customization options.
+   * @returns  A Promise object that resolves to an array containing {@linkcode PaymentMethod} objects.
+   */
+  getSupportedPaymentMethods(options: GetSupportedPaymentMethodsOptions): Promise<PaymentMethod[]>;
+}
+
+/**
+ * PaymentMethod values.
+ */
+export type PaymentMethod = 'TAP_TO_PAY' | 'CREDIT_CARD_DETAILS' | 'PAY_VIA_LINK';
+
+/**
+ * GetSupportedPaymentMethodsOptions interface.
+ */
+export interface GetSupportedPaymentMethodsOptions {
+  countryIsoCode?: string;
+  merchantAccountId?: string;
+  permissionRationaleText?: string;
+}
+
+/**
+ * CollectPaymentOptions interface.
+ */
+export interface CollectPaymentOptions {
+  amount: number;
+  paymentMethod: PaymentMethod;
+  currencyIsoCode: string;
+  merchantAccountId: string;
+  merchantName: string;
+  payerAccountId?: string;
+  sourceObjectIds?: string[];
+  permissionRationaleText?: string;
+}
+
+/**
+ * CollectPaymentResult interface.
+ */
+export interface CollectPaymentResult {
+  gatewayRefId?: string;
+  guid?: string;
+  paymentGatewayId?: string;
+  status?: string;
+}
+
+/**
+ * PaymentsServiceFailure interface.
+ */
+export interface PaymentsServiceFailure {
+  code: PaymentsServiceFailureCode;
+  message: string;
+}
+
+/**
+ * Possible failure codes.
+ */
+export type PaymentsServiceFailureCode =
+  | 'USER_DISMISSED' // User cancelled the operation.
+  | 'USER_DENIED_PERMISSION' // Permission to access device location is denied.
+  | 'SERVICE_NOT_ENABLED' // The service is not enabled and therefore cannot be used.
+  | 'UNKNOWN_REASON'; // An error happened in the native code that is not permission based. Will give more information in the PaymentsServiceFailure message.
+```

package/skills/validating-slds/SKILL.md

@@ -0,0 +1,262 @@
+---
+name: validating-slds
+description: "Audit Lightning Web Components for SLDS compliance and produce a scored quality report. Runs the SLDS linter, analyzes CSS for theming hook usage and pairing, checks HTML for accessibility attributes, and scores findings across categories into an overall grade. Use when asked to \"score my component\", \"SLDS scorecard\", \"quality report\", \"audit SLDS compliance\", \"how good is my SLDS\", \"check component quality\", \"rate my component\", \"evaluate my component\", \"is this component ready to ship?\", \"look at my LWC for issues\", \"audit this before I submit\", \"review my component before code review\", or any time a user wants a quality assessment or production-readiness check on an LWC or SLDS component. Not for fixing violations (use uplifting-components-to-slds2) or building new components (use applying-slds)."
+metadata:
+  version: "1.0"
+---
+
+# SLDS Quality Audit
+
+Audit Lightning Web Components for SLDS compliance and produce an automated scorecard plus a required manual review gate. Combines SLDS linter output with supplementary static analysis to catch what the linter misses.
+
+## Scope
+
+Also valid for: auditing SLDS compliance across a project or component set, and before/after quality comparison after making changes.
+
+Not for:
+- **Fixing** linter violations — use `uplifting-components-to-slds2` instead
+- **Building** new components — use `applying-slds` instead
+- **Just running the linter** — run `npx @salesforce-ux/slds-linter@latest lint .` directly
+- **Full WCAG accessibility audit** — this skill checks attribute presence only (labels, alt text, focus indicators), not contrast ratios, keyboard flows, or screen reader behavior
+- **Framework-specific template auditing** beyond `.css`, `.html`, and `.js` files — JSX/TSX/Vue/Svelte outputs need additional manual review
+
+---
+
+## Quality Validation Process
+
+```
+1. Run SLDS Linter     → Collect violation counts (linter's job)
+2. Run Analyze Script  → Check what linter doesn't cover (supplementary)
+3. Agent Review        → Required manual review gate
+4. Score & Grade       → Compute automated score + final recommendation
+5. Generate Report     → Produce formatted scorecard
+```
+
+## Step 1: Run SLDS Linter
+
+Run the linter to collect baseline violation data:
+
+```bash
+npx @salesforce-ux/slds-linter@latest lint <component-path> 2>&1
+```
+
+Count violations by rule. These feed directly into the **Linter Compliance** score:
+
+| Rule | Impact |
+|------|--------|
+| `slds/class-override` | Breaks theming, dark mode |
+| `slds/lwc-token-to-slds-hook` | SLDS 1 technical debt |
+| `slds/no-hardcoded-values` | Breaks theming, accessibility |
+
+**Linter Compliance Score** = `100 - (total_violations × 10)`, minimum 0.
+
+**If the linter is unavailable** (no Node.js, no network access, CI sandbox restrictions): skip this step, note "Linter not run" in the report header, mark Linter Compliance as N/A, and compute the Overall score using the remaining 4 categories renormalized to 100%:
+
+```
+Overall (linter unavailable) = (Theming × 0.29) + (Accessibility × 0.29)
+                              + (CodeQuality × 0.21) + (ComponentUsage × 0.21)
+```
+
+## Step 2: Run Supplementary Analysis
+
+Run the analyze script to catch issues the linter doesn't cover. The bundled analyzer scans `.css`, `.html`, and `.js` files only:
+
+```bash
+node scripts/analyze-quality.cjs <component-path>
+```
+
+The script outputs JSON with findings organized by severity. It checks:
+
+### CSS Checks (linter-complementary)
+
+| Check | What It Catches | Severity |
+|-------|----------------|----------|
+| Missing fallbacks | `var(--slds-g-*)` without a fallback value | Critical |
+| Invented hooks (T051) | `--slds-g-*` tokens not found in `hooks-index.json` (requires `--hooks-index`) | Critical |
+| Hook pairing | Background hooks without matching foreground hooks | Warning |
+| `!important` | Specificity overrides | Warning |
+| Magic pixel values | Hardcoded `px` not using spacing hooks | Warning |
+| High z-index | z-index values > 99 | Warning |
+| Outline removal | `outline: none` without alternative focus style | Warning |
+
+### JS Checks
+
+| Check | What It Catches | Severity |
+|-------|----------------|----------|
+| Inline style assignment | `.style.*=` direct property assignment | Warning |
+| SLDS class manipulation | Dynamic `.classList.add('slds-*')` manipulation | Warning |
+
+### HTML Checks
+
+| Check | What It Catches | Severity |
+|-------|----------------|----------|
+| LBC input labels | `<lightning-input>` without `label` attribute | Critical |
+| Icon alt text | `<lightning-icon>` without `alternative-text` | Critical |
+| Image alt text | `<img>` without `alt` | Critical |
+| Heading hierarchy | Skipped heading levels (h2 to h4) | Warning |
+| Positive tabindex | `tabindex` values other than 0 or -1 | Warning |
+| Clickable divs | `<div onclick>` instead of `<button>` | Warning |
+| Inline styles | `style="..."` attributes | Warning |
+| Native elements | `<input>`, `<button>`, `<select>` where LBC alternatives exist | Warning |
+
+### Hook Pairing Validation
+
+The script checks that background/foreground hooks are semantically paired:
+
+```
+surface-* backgrounds     → on-surface-* text
+surface-container-* bg    → on-surface-* text
+accent-* backgrounds      → on-accent-* text
+accent-container-* bg     → on-accent-* text
+```
+
+> **Limitation:** Hook pairing is checked at the file level, not per-selector. A file with `surface-1` in `.classA` and `on-accent-1` in `.classB` would pass because both surface and accent families are present. Review pairing correctness per-selector during manual review (Step 3).
+
+### Invented Hook Detection (T051)
+
+The script cross-references every `--slds-g-*` token in CSS against `hooks-index.json`. Any hook not found in metadata is flagged as critical — this catches the most common agent mistake of inventing hooks from naming patterns.
+
+## Step 3: Agent Manual Review
+
+These checks require understanding the component's purpose and cannot be automated reliably. Review each and classify findings as either:
+
+- **Blocking** — incorrect blueprint structure, missing required states, or semantic/interaction issues that make the component not production-ready
+- **Advisory** — worthwhile improvements that do not block shipping on their own
+
+| Review Area | What to Look For |
+|-------------|-----------------|
+| Loading states | Does the component show a spinner or skeleton when fetching data? |
+| Error states | Are errors surfaced to the user with actionable messages? |
+| Empty states | Is there a meaningful empty state when no data exists? |
+| Disabled states | Do interactive elements visually and functionally handle disabled? |
+| Semantic HTML | Are `<nav>`, `<article>`, `<section>` used where appropriate? |
+| SLDS blueprint compliance | Do cards, modals, forms follow SLDS blueprint structure? |
+
+> Manual review findings are not automated, but they do affect the final recommendation. Do not report an automated grade as the only verdict.
+
+## Step 4: Calculate Automated Scores and Final Recommendation
+
+### Component Complexity
+
+Before scoring, classify the component to give the score context:
+
+| Complexity | Criteria | Report Note |
+|------------|----------|-------------|
+| Small | 1-2 files, < 100 total lines | Score is high-confidence (small surface area) |
+| Medium | 3-6 files, 100-500 total lines | Score reflects typical component |
+| Large | 7+ files, 500+ total lines | Score reflects absolute issue count — even well-built large components may score lower |
+
+Include the complexity classification in the report header. This prevents misreading a "B" on a 1000-line component vs. a "B" on a 20-line component.
+
+### Automated Scoring Formula
+
+```
+Category Score = 100 - (critical_issues × 10) - (warnings × 3) - (info × 1)
+Minimum score: 0
+```
+
+### Categories and Weights
+
+| Category | Weight | Source |
+|----------|--------|--------|
+| Linter Compliance | 30% | SLDS linter output (Step 1) |
+| Theming | 20% | Script: fallbacks, hook pairing (Step 2) |
+| Accessibility | 20% | Script: labels, alt text, focus (Step 2) |
+| Code Quality | 15% | Script: !important, inline styles, z-index (Step 2) |
+| Component Usage | 15% | Script: native elements (Step 2) plus manual semantic/blueprint review (Step 3) |
+
+### Automated Overall Score
+
+```
+Overall = (Linter × 0.30) + (Theming × 0.20) + (Accessibility × 0.20)
+        + (CodeQuality × 0.15) + (ComponentUsage × 0.15)
+```
+
+### Automated Grade Thresholds
+
+| Score | Grade | Meaning |
+|-------|-------|---------|
+| 90-100 | A | Excellent automated score |
+| 80-89 | B | Good automated score |
+| 70-79 | C | Acceptable automated score |
+| 60-69 | D | Weak automated score |
+| 0-59 | F | Failing automated score |
+
+### Manual Review Gate
+
+After computing the automated score, apply the manual review outcome:
+
+| Gate | When to use it | Effect on final recommendation |
+|------|----------------|-------------------------------|
+| Pass | No manual findings | Final recommendation can follow the automated score |
+| Advisory | Only non-blocking manual findings | Final recommendation can be "Ready with follow-ups" at best |
+| Blocking | One or more blocking manual findings | Final recommendation is **not ready for production**, regardless of automated grade |
+
+### Final Recommendation Rules
+
+Use both the automated score and the manual review gate:
+
+| Final Recommendation | Conditions |
+|----------------------|------------|
+| Ready for production | Automated grade A/B, no critical findings, manual gate = Pass |
+| Ready with follow-ups | Automated grade A/B, no critical findings, manual gate = Advisory |
+| Needs work | Any critical findings, automated grade C/D, or manual gate = Blocking |
+| Failing | Automated grade F |
+
+## Step 5: Generate Quality Report
+
+Use the template in **[report-format.md](references/report-format.md)** to produce the final report. Default to the **compact format** for initial output and expand sections on request.
+
+The report includes:
+- Executive summary with automated grade and final recommendation
+- Manual review gate outcome (`Pass`, `Advisory`, or `Blocking`)
+- Scores by category with visual indicators
+- Detailed findings organized by severity
+- Specific code locations and recommendations
+- Checklist of required actions
+
+---
+
+## Quick Validation Mode
+
+For a rapid quality check without full analysis:
+
+1. Run linter: `npx @salesforce-ux/slds-linter@latest lint <path>`
+2. Count violations by type
+3. Report summary only
+
+```
+Quick Quality Check: <component-name>
+─────────────────────────────────────
+Linter Violations:
+  • Class Override:     0
+  • Deprecated Tokens:  3
+  • Hardcoded Values:   5
+
+Quick Automated Grade: C (estimated)
+Run full validation for detailed report.
+```
+
+---
+
+## Edge Cases and False Positives
+
+| Situation | Guidance |
+|-----------|----------|
+| **Headless components** (JS-only, no HTML) | Skip HTML checks; score only CSS + linter categories |
+| **Wrapper/container components** | May legitimately have minimal CSS; don't penalize low hook usage |
+| **Intentional native elements** | `<button>` inside custom SLDS blueprints is correct; suppress C002 if inside an `slds-*` blueprint structure |
+| **Components outside LEX** | LWR/Experience Cloud components may not use Lightning Base Components; note context in report |
+| **Test/demo components** | Lower the bar — note in report but don't block on warnings |
+
+If a check produces a false positive, note it in the report as "suppressed" with justification rather than silently dropping it.
+
+---
+
+## References
+
+- **[Quality Checks](references/quality-checks.md)** - Complete list of all quality checks with detection patterns
+- **[Report Format](references/report-format.md)** - Quality report template and formatting guide
+- **[Analyze Script](scripts/analyze-quality.cjs)** - Automated analysis for linter-complementary checks
+- **uplifting-components-to-slds2 skill** - How to fix linter violations
+- **applying-slds skill** - Guide for building new components with correct patterns