Add {vector-sizing-calculator} directive

[KOTungseth]

Summary

Wire the {vector-sizing-calculator} custom directive into elastic/docs-builder so the
interactive vector sizing calculator can be embedded in docs-content pages.

Implementation: #2736

Status

Item	Status
Directive block + view + view model	Done in PR #2736
Parser/renderer wiring	Done
Web component (React/EUI) in site bundle	Done
Syntax docs + directive tests	Done
PR merged to main	Pending

Implementation notes

• Directive: src/Elastic.Markdown/Myst/Directives/VectorSizing/
• Web component: src/Elastic.Documentation.Site/Assets/web-components/VectorSizingCalculator/
• Asset delivery: Parcel bundle via main.ts (registers <vector-sizing-calculator>), not a standalone IIFE script tag
• Local preview: dotnet run --project src/tooling/docs-builder -- serve → /syntax/vector-sizing-calculator
• Integration guide: tools/vector_sizing_calculator/INTEGRATION.md

Out of scope (this issue)

• Embedding in docs-content (see docs-content-internal#1030)
• Formula accuracy / BBQ constant (see docs-content-internal#1031)
• Design sign-off (see Design vector sizing calculator UI #3052)
• Landing page / publish (see docs-content-internal#1032–1033)

Prerequisites

• Single implementation chosen (PR Add Vector Sizing Calculator #2736)
• BBQ constant validated with Search Engineering (blocks launch accuracy; tracked in docs-content-internal#1031)

Acceptance criteria

• {vector-sizing-calculator} recognized by the build without errors
• Directive renders <vector-sizing-calculator> in output HTML
• Web component loads on pages using the directive (site bundle)
• Unit tests pass (VectorSizingBlockTests)
• PR Add Vector Sizing Calculator #2736 merged
• Full integration checklist passed before docs-content publish (docs-content-internal#1031)

Owner

Docs Eng — @itsalexcm

[itsalexcm]

Update from Docs Eng / contributor work on feat/vector-sizing-calculator:

Done (merged to branch, ready for PR review):

• Directive implementation under src/Elastic.Markdown/Myst/Directives/VectorSizing/ (VectorSizingBlock, VectorSizingViewModel, VectorSizingView).
• Registration in DirectiveBlockParser and rendering in DirectiveHtmlRenderer (Razor slice outputs <vector-sizing-calculator></vector-sizing-calculator>).
• Unit tests: VectorSizingBlockTests (directive parses and HTML contains the custom element).
• Staging docs under tools/vector_sizing_calculator/ updated: duplicate C# snippets removed from docs-builder-directive/; integration notes point at the in-repo source of truth.

Preview for reviewers:

• Docset page with a live directive block: docs/syntax/vector-sizing-calculator.md (also linked from docs/syntax/directives.md and _docset.yml).
  Local check: docs-builder serve → /syntax/vector-sizing-calculator.

Note vs issue checklist: the interactive widget is loaded via the existing site asset pipeline (main.ts dynamic import → VectorSizingCalculatorComponent), not a standalone <script src="/_static/vector-sizing-calculator.iife.js">. If the acceptance bar is strictly the _static IIFE, we should either add that artifact or align the issue wording with the agreed delivery path.

[itsalexcm]

Status update (docs-builder)

Work for the {vector-sizing-calculator} directive has landed on branch feat/vector-sizing-calculator and been pushed to origin (includes a merge from origin/main plus follow-up site commits).

Done (aligned with this issue)

• Directive wired in Elastic.Markdown (VectorSizing directive, parser/renderer registration).
• Web component shipped under site assets and hooked into the docs bundle (see src/Elastic.Documentation.Site/Assets/ — main.ts / styles as needed).
• Output renders the <vector-sizing-calculator> custom element for pages that use the directive.

Follow-ups / notes

• Recent UI/UX polish (layout, slider styling, dynamic quantization copy, replicas input behavior, hiding quantization when only None, 1k vectors preset, CTA transition, etc.) goes beyond the original “out of scope” UI line in the issue description; worth keeping formula accuracy / Vector Search items on their own tracker if still open.
• Integration checklist from the issue (all element-type × quantization paths, DiskBBQ, cluster totals, formulas panel): the current embed has been simplified (e.g. formulas/breakdown panels removed in favor of a leaner results panel) — if the checklist is still required verbatim, call out gaps explicitly in review.

PR

Use the open PR for feat/vector-sizing-calculator (or open one if not linked yet) and link it here under Development when ready.

cc @KOTungseth

[itsalexcm]

Update (post-merge / follow-up)

Latest work on feat/vector-sizing-calculator is pushed; see PR #2736: #2736

Shipped or adjusted since the last comment

• Marketing CTAs removed from the embedded calculator (no “Get started free” / “Contact us” in the results column), per product request.
• Build reliability: parcel build --no-cache in src/Elastic.Documentation.Site/package.json so Parcel does not serve stale bundles after TSX changes (we hit a case where .parcel-cache kept old main.js even when source was correct; incognito did not help because the server was literally serving old JS).

Still accurate from the original issue

• Directive + <vector-sizing-calculator> embed path remains the integration model (main site bundle, not a separate vector-sizing-calculator.iife.js as in the early checklist — align acceptance wording with what PR Add Vector Sizing Calculator #2736 actually ships).

Acceptance checklist note

• UI is simplified vs the issue’s mention of cluster totals / formulas panel; if those remain strict acceptance items, call them out explicitly in PR review or spin a follow-up issue.

cc @KOTungseth

[itsalexcm]

Updated the issue body to reflect the current state of work in PR #2736 (single implementation, Parcel bundle delivery, AC checklist).

If you prefer to keep the original text and track progress via comments only, let me know and I can revert the body changes.

[cotti]

AI triage

Automated investigation against the current codebase. A human still needs to confirm before any code change.

Original concern

Wire a new {vector-sizing-calculator} directive into docs-builder so an interactive vector‑storage sizing widget can be embedded in docs pages.

Findings

• src/Elastic.Markdown/Myst/Directives/DirectiveBlockParser.cs:93-177 — the directive registry is a chain of if (info.IndexOf("{...}") > 0) checks. There is no {vector-sizing-calculator} branch, so on main the directive falls through to UnknownDirectiveBlock at L177 and is not recognized.
• src/Elastic.Documentation.Site/Assets/main.ts:38-43 — dynamic web-component imports. No vector-sizing component is imported, and there is no customElements.define('vector-sizing-calculator', …) anywhere under Assets/, so the <vector-sizing-calculator> element does not ship today. (Existing pattern, for reference: src/Elastic.Documentation.Site/Assets/web-components/AskAi/AskAi.tsx:106.)
• The full implementation lives in PR #2736 ("Add Vector Sizing Calculator", @john-wagster) — OPEN, reviewDecision: CHANGES_REQUESTED, base main, head feat/vector-sizing-calculator, created 2026-02-18, updated 2026-05-26. Not merged.
• The directive/web-component commits exist only on origin/feat/vector-sizing-calculator (e.g. 9b0ca4c4 directive wiring, f3a750df web component, 54bb5a71 preview page). git merge-base --is-ancestor 9b0ca4c4 origin/main returns NO — nothing from this work is on main.
• Acceptance-criteria drift flagged by the contributor (comments 2026-04-13 / 2026-04-21): delivery is via the Parcel main bundle, not the _static/...iife.js artifact the original checklist implied, and the UI was simplified (formulas / cluster-totals panels removed) vs. the issue's integration checklist.
• Formula accuracy / BBQ constant is unresolved and owned by Search Engineering (issue body prereq, tracked in docs-content-internal#1031); design sign-off is tracked separately in Design vector sizing calculator UI #3052.

Verdict

Needs stakeholder input

A near-complete implementation already exists in PR #2736, but nothing has merged to main (the directive and web component are absent from the current tree) and the PR is blocked at CHANGES_REQUESTED. The remaining work is less "write the code" and more cross-functional decisions: aligning the acceptance criteria with the actual delivery path, signing off on the simplified UI, confirming who owns/validates the sizing formula, and resolving the open review. Routing to the relevant audiences rather than treating it as a quick fix.

Proposal

Open questions grouped by audience:

• Product — Is the vector-sizing calculator in scope for docs-builder to host and maintain, and who owns the sizing formula long-term? The BBQ constant still needs validation with Search Engineering (docs-content-internal#1031) before launch.
• Writer — Confirm the final author-facing syntax {vector-sizing-calculator} and its documentation home (docs/syntax/… + listing in directives.md); is the preview page the intended canonical example?
• UX — Sign off on the simplified calculator UI (formulas / cluster-totals panels removed). Does the Design vector sizing calculator UI #3052 design approve the leaner results panel?
• Eng — Reconcile the acceptance criteria with the shipped delivery (Parcel main bundle vs. the _static IIFE in the original checklist) and clear the CHANGES_REQUESTED review on PR Add Vector Sizing Calculator #2736.

Related issues

• Design vector sizing calculator UI #3052 (open) — "Design vector sizing calculator UI" (design sign-off; referenced in this issue's body).
• Cross-repo trackers referenced in the body but not verifiable here: docs-content-internal#1030 (embed), #1031 (formula/BBQ), #1032–1033 (landing/publish).

Notes

• Partial-fix PR: Add Vector Sizing Calculator #2736 — pushed to origin/feat/vector-sizing-calculator, not merged to main. Do not treat the directive as available until that PR lands.
• Suggested labels: ai-triaged, ai:product-question, ai:writer-question, ai:eng-question, ai:ux-question (keeping existing design).