प्लेसहोल्डर सिस्टम

प्लेसहोल्डर सिस्टम पाठकों को पूरे दस्तावेज़ में IP एड्रेस, ASN, और अन्य डिप्लॉयमेंट-विशिष्ट मानों को कस्टमाइज़ करने की सुविधा देता है। लेखक अपने Markdown में टोकन लिखते हैं; ब्राउज़र रनटाइम पर उन्हें उपयोगकर्ता द्वारा प्रदान किए गए मानों से बदल देता है।

टोकन प्रारूप

टोकन निम्नलिखित regex पैटर्न का पालन करते हैं:

x([A-Z][A-Z0-9_]+)x

टोकन एक लोअरकेस x से शुरू और समाप्त होता है और इसमें एक अपरकेस आइडेंटिफायर होता है। उदाहरण के लिए, xCUSTOMER_ASNx CUSTOMER_ASN प्लेसहोल्डर को संदर्भित करता है।

regex src/scripts/placeholder-dom.ts में परिभाषित है:

const PH_REGEX = /x([A-Z][A-Z0-9_]+)x/g;

प्लेसहोल्डर परिभाषाएँ

सभी प्लेसहोल्डर src/data/placeholders.json में घोषित हैं। प्रत्येक प्रविष्टि का यह स्वरूप है:

{
  "CUSTOMER_ASN": {
    "type": "text",
    "default": "64496",
    "description": "Your public ASN (registered with ARIN/RIR)"
  }
}

फ़ील्ड	आवश्यक	विवरण
type	हाँ	फ्री-फॉर्म इनपुट के लिए "text", सिलेक्ट मेन्यू के लिए "dropdown"
default	हाँ	पाठक द्वारा कुछ भी बदलने से पहले दिखाया जाने वाला प्रारंभिक मान
description	हाँ	फॉर्म में प्रदर्शित लेबल
options	केवल dropdown के लिए	अनुमत मानों की सूची

स्टेट प्रबंधन

src/lib/placeholder-store.ts सभी प्लेसहोल्डर स्टेट को संभालता है।

स्टोरेज

मान localStorage में f5xc-placeholders की के अंतर्गत संग्रहीत किए जाते हैं। स्टोर चार फ़ंक्शन प्रदान करता है:

फ़ंक्शन	उद्देश्य
getDefaults()	JSON से प्रत्येक प्लेसहोल्डर की को उसके default मान का मैप लौटाता है
loadValues()	localStorage से पढ़ता है, उपलब्ध न होने पर getDefaults() पर फॉलबैक करता है
saveValues(values)	वर्तमान मैप को localStorage में लिखता है
clearValues()	localStorage प्रविष्टि को हटाता है

फ़ील्ड समूह

FIELD_GROUPS फॉर्म UI के लिए प्लेसहोल्डर कीज़ को लेबल वाले अनुभागों में व्यवस्थित करता है:

export const FIELD_GROUPS: FieldGroup[] = [
  { label: 'Data Center & Scrubbing Centers', keys: ['DC_NAME', 'CENTER_1', 'CENTER_2'] },
  { label: 'Protected Prefixes', keys: ['PROTECTED_CIDR_V4', 'PROTECTED_NET_V4', ...] },
  { label: 'BGP', keys: ['CUSTOMER_ASN', 'F5_XC_ASN', 'BGP_PASSWORD'] },
  // ... और अधिक समूह
];

कम्प्यूटेड वैल्यू

कुछ मान सीधे दर्ज करने के बजाय उपयोगकर्ता इनपुट से व्युत्पन्न होते हैं। getComputedValues() लुकअप टेबल से इनकी गणना करता है:

const cidrToMask: Record<string, string> = {
  '/24 (256 IPs)': '255.255.255.0',
  '/23 (512 IPs)': '255.255.254.0',
  // ...
};

दो कम्प्यूटेड प्लेसहोल्डर उत्पन्न होते हैं:

कम्प्यूटेड की	व्युत्पन्न स्रोत	उदाहरण
PROTECTED_MASK_V4	cidrToMask लुकअप के माध्यम से PROTECTED_CIDR_V4	255.255.255.0
PROTECTED_PREFIX_V4	cidrToShort के माध्यम से PROTECTED_NET_V4 + PROTECTED_CIDR_V4	192.0.2.0/24

getAllValues() उपयोगकर्ता द्वारा दर्ज मानों को कम्प्यूटेड मानों के साथ मर्ज करता है, जिससे प्रतिस्थापन के लिए एक पूर्ण मैप मिलता है।

इवेंट एमिशन

emitChange() document पर एक placeholder-change CustomEvent डिस्पैच करता है जिसमें detail के रूप में पूर्ण वैल्यू मैप होता है:

export function emitChange(values: Record<string, string>) {
  document.dispatchEvent(
    new CustomEvent('placeholder-change', { detail: getAllValues(values) }),
  );
}

यह इवेंट DOM span अपडेट और Mermaid री-रेंडरिंग दोनों को संचालित करता है।

React फॉर्म कंपोनेंट

src/components/PlaceholderForm.tsx संपादन UI प्रदान करता है।

• स्टेट: useState जो loadValues() से इनिशियलाइज़ होता है
• माउंट पर: useEffect प्रारंभिक DOM प्रतिस्थापन ट्रिगर करने के लिए emitChange() कॉल करता है
• handleChange: React स्टेट अपडेट करता है, saveValues() और emitChange() कॉल करता है
• handleReset: clearValues() कॉल करता है, स्टेट को getDefaults() पर रीसेट करता है, चेंज एमिट करता है
• रेंडरिंग: FIELD_GROUPS पर इटरेट करता है, प्रति समूह एक <fieldset> रेंडर करता है। प्रत्येक की को या तो <input> (text type) या <select> (dropdown type) मिलता है
• लेआउट: फॉर्म एक <details> एलिमेंट में रैप्ड है, डिफ़ॉल्ट रूप से कोलैप्स्ड

Astro रैपर

src/components/PlaceholderFormWrapper.astro React कंपोनेंट को Astro पेज से जोड़ता है:

<PlaceholderForm client:only="react" />

<script>
  import '../scripts/placeholder-dom.ts';
</script>

client:only="react" Astro को बताता है कि कंपोनेंट को पूरी तरह से क्लाइंट पर हाइड्रेट करना है (कोई SSR नहीं)। <script> टैग DOM वॉकर को इम्पोर्ट करता है ताकि यह इस रैपर को शामिल करने वाले प्रत्येक पेज पर चले।

रैपर फॉर्म स्टाइलिंग के लिए ग्लोबल CSS भी इंजेक्ट करता है (.ph-form-wrapper, .ph-grid, .ph-value, आदि)।

DOM वॉकर

src/scripts/placeholder-dom.ts क्लाइंट-साइड टोकन प्रतिस्थापन को संभालता है।

प्रारंभिक वॉक

पेज लोड पर, init() चलता है:

1. .sl-markdown-content को रूट के रूप में चुनता है (उपलब्ध न होने पर document.body पर फॉलबैक करता है)
2. walkTextNodes(root, values) कॉल करता है जो NodeFilter.SHOW_TEXT के साथ document.createTreeWalker का उपयोग करता है
3. टोकन regex से मैच करने वाले प्रत्येक टेक्स्ट नोड के लिए, इसे प्लेन टेक्स्ट नोड्स और <span data-ph="KEY" class="ph-value"> एलिमेंट्स के डॉक्यूमेंट फ्रैगमेंट में विभाजित करता है
4. मूल टेक्स्ट नोड को फ्रैगमेंट से बदल देता है

वॉक के बाद, DOM में रॉ टोकन के बजाय data-ph एट्रिब्यूट वाले span होते हैं।

बाद के अपडेट

जब फॉर्म placeholder-change इवेंट एमिट करता है, updateSpans() चलता है:

document.querySelectorAll<HTMLSpanElement>('span[data-ph]').forEach((span) => {
  const name = span.getAttribute('data-ph')!;
  if (values[name] !== undefined) {
    span.textContent = values[name];
  }
});

यह ट्री को फिर से वॉक करने से बचाता है — यह सीधे span टेक्स्ट कंटेंट को अपडेट करता है।

इवेंट लिसनर्स

स्क्रिप्ट दो लिसनर्स रजिस्टर करता है:

इवेंट	हैंडलर	उद्देश्य
placeholder-change	handleChange	Span अपडेट करता है और Mermaid डायग्राम री-रेंडर करता है
astro:page-load	init	Astro क्लाइंट-साइड नेविगेशन के बाद DOM को फिर से वॉक करता है

कैसे करें: नया प्लेसहोल्डर जोड़ें

1. JSON प्रविष्टि जोड़ें src/data/placeholders.json में:

   "MY_NEW_VALUE": {
     "type": "text",
     "default": "example",
     "description": "Description shown in the form"
   }

2. की को एक फ़ील्ड समूह में जोड़ें src/lib/placeholder-store.ts में। या तो इसे किसी मौजूदा समूह के keys ऐरे में जोड़ें या FIELD_GROUPS में एक नया समूह बनाएँ।

3. कंटेंट में टोकन का उपयोग करें: किसी भी .mdx फ़ाइल में xMY_NEW_VALUEx लिखें। DOM वॉकर रनटाइम पर इसे बदल देगा।

कैसे करें: कम्प्यूटेड वैल्यू जोड़ें

कम्प्यूटेड वैल्यू अन्य प्लेसहोल्डर से व्युत्पन्न होती हैं। एक जोड़ने के लिए:

1. src/lib/placeholder-store.ts में एक लुकअप टेबल जोड़ें (यदि आवश्यक हो), cidrToMask के पैटर्न का अनुसरण करते हुए।

2. getComputedValues() को नई व्युत्पन्न की शामिल करने के लिए विस्तारित करें:

   export function getComputedValues(values: Record<string, string>): Record<string, string> {
     // ... मौजूदा लॉजिक
     return {
       PROTECTED_MASK_V4: mask,
       PROTECTED_PREFIX_V4: `${net}${short}`,
       MY_COMPUTED: derivedValue,  // यहाँ जोड़ें
     };
   }

3. किसी भी अन्य टोकन की तरह कंटेंट में xMY_COMPUTEDx का उपयोग करें। कम्प्यूटेड वैल्यू को placeholders.json प्रविष्टि या फ़ील्ड समूह की आवश्यकता नहीं होती — वे फॉर्म से अदृश्य होती हैं।