# Typst टेम्पलेट के लिए फ़ॉर्म

अपने Typst फ़ंक्शन को एक फ़ॉर्म दें, ताकि रिपोर्ट भरने वालों को Visual mode में फ़ंक्शन-कॉल सिंटैक्स की जगह लेबल वाले फ़ील्ड दिखें।

Typst टेम्पलेट अक्सर अपने फ़ंक्शन साथ लाता है: कवर पेज, इन्फ़ो बॉक्स, साइन-ऑफ़ ब्लॉक। रिपोर्ट लिखने वाला उन्हें कॉल करता है, जैसे `#info-box(title: "Supply risk", tone: "risk")[...]`। अगर आप टेम्पलेट सँभालते हैं, तो हर फ़ंक्शन के आर्ग्युमेंट एक बार बता सकते हैं। फिर Visual mode उस फ़ंक्शन की हर कॉल को एक फ़ॉर्म की तरह दिखाता है: लेबल वाले फ़ील्ड, तय विकल्पों के लिए सूची, हाँ या नहीं के लिए स्विच। किसी फ़ील्ड को बदलने पर `.typ` फ़ाइल में केवल वही एक आर्ग्युमेंट दोबारा लिखा जाता है, इसलिए रिपोर्ट साधारण Typst सोर्स रहती है जो उसी तरह कंपाइल होता है।

## पाठक को क्या दिखता है

अपनी अलग लाइनों में लिखी कॉल एक **कार्ड** बन जाती है। कार्ड का हेडर फ़ॉर्म का नाम दिखाता है और, अगर आप चुनें, तो एक छोटा सारांश, जैसे बॉक्स का शीर्षक। हर आर्ग्युमेंट को उसके लेबल और एक कंट्रोल वाली पंक्ति मिलती है।

वाक्य के भीतर की कॉल, जैसे `#badge("review")`, टेक्स्ट की लाइन में एक **चिप** बन जाती है। चिप पर क्लिक करने से वही फ़ील्ड एक छोटे पॉपओवर में खुलते हैं।

टेक्स्ट फ़ील्ड और मार्कअप फ़ील्ड तब सहेजे जाते हैं जब आप Enter दबाते हैं (कई लाइन वाले फ़ील्ड में ⌘ Enter या Ctrl Enter) या फ़ील्ड छोड़ देते हैं। Esc पुरानी वैल्यू लौटा देता है। सूचियाँ और स्विच तुरंत सहेजे जाते हैं। हर बदलाव एक undo चरण है।

कर्सर को किसी कॉल में ले जाने पर उसका सोर्स दिखता है, Visual mode के किसी भी दूसरे एलिमेंट की तरह। कार्ड पर **Edit in source** भी यही करता है।

## फ़ॉर्म कहाँ घोषित करें

दो जगहें हैं, फ़ॉर्मैट एक ही है:

- **पैकेज में।** पैकेज की `typst.toml` में `[tool.oleafly]` सेक्शन जोड़ें। Typst `[tool.*]` सेक्शन दूसरे टूल के लिए रखता है, इसलिए पैकेज फिर भी हर जगह इंस्टॉल और कंपाइल होता है। यह `@local` पैकेज के लिए और Typst Universe के `@preview` पैकेज के लिए काम करता है।
- **प्रोजेक्ट में।** प्रोजेक्ट के भीतर साधारण `.typ` फ़ाइलों के रूप में रखे टेम्पलेट के लिए, प्रोजेक्ट के रूट पर `oleafly-forms.toml` बनाएँ। हर फ़ॉर्म `module` से उस फ़ाइल का नाम भी बताता है जो फ़ंक्शन को परिभाषित करती है।

पैकेज का एक फ़ॉर्म:

```toml
[tool.oleafly]
schema = 1

[[tool.oleafly.forms]]
function = "info-box"
label = "Info box"
summary = "title"

  [[tool.oleafly.forms.fields]]
  arg = "title"
  kind = "text"
  label = "Heading"
  placeholder = "Short heading"
  required = true

  [[tool.oleafly.forms.fields]]
  arg = "tone"
  kind = "choice"
  label = "Tone"
  default = "note"
  options = [{ value = "note", label = "Note" }, { value = "risk", label = "Risk" }, "neutral"]

  [[tool.oleafly.forms.fields]]
  arg = 0
  kind = "content"
  label = "Text"
```

प्रोजेक्ट का एक फ़ॉर्म, `oleafly-forms.toml` में:

```toml
[tool.oleafly]
schema = 1

[[tool.oleafly.forms]]
module = "template/memo.typ"
function = "memo-header"
label = "Memo header"
fields = [
  { arg = "to", kind = "text", label = "To" },
  { arg = "subject", kind = "text", label = "Subject" },
]
```

## कुंजियाँ

`schema = 1` ज़रूरी है। जिस फ़ाइल में यह न हो, या कोई और संख्या हो, उसे नज़रअंदाज़ कर दिया जाता है।

हर `[[tool.oleafly.forms]]` प्रविष्टि में ये होते हैं:

| कुंजी | ज़रूरी | मतलब |
| --- | --- | --- |
| `function` | हाँ | फ़ंक्शन का नाम, एक Typst आइडेंटिफ़ायर के रूप में। हाइफ़न चलते हैं। |
| `module` | केवल `oleafly-forms.toml` में | वह प्रोजेक्ट फ़ाइल जो फ़ंक्शन को परिभाषित करती है, प्रोजेक्ट रूट के सापेक्ष, फ़ोल्डरों के बीच `/` के साथ। |
| `label` | नहीं | कार्ड और चिप पर फ़ॉर्म का नाम। डिफ़ॉल्ट फ़ंक्शन का नाम है। |
| `summary` | नहीं | वह आर्ग्युमेंट जिसकी वैल्यू लेबल के बगल में दिखती है, फ़ील्ड के `arg` की तरह लिखा जाता है। |
| `fields` | हाँ | एक या अधिक फ़ील्ड। |

हर फ़ील्ड में ये होते हैं:

| कुंजी | ज़रूरी | मतलब |
| --- | --- | --- |
| `arg` | हाँ | नामित आर्ग्युमेंट के लिए एक नाम (`"title"`), या पोज़िशनल आर्ग्युमेंट के लिए एक संख्या (`0` पहला है)। अंत का `[...]` ब्लॉक कोष्ठक वाले आर्ग्युमेंट के बाद का एक पोज़िशनल आर्ग्युमेंट गिना जाता है। |
| `kind` | हाँ | `text`, `content`, `choice`, `number` या `toggle`। |
| `label` | हाँ | फ़ील्ड का लेबल। |
| `help` | नहीं | फ़ील्ड के नीचे एक छोटा नोट। |
| `placeholder` | नहीं | खाली फ़ील्ड में ग्रे टेक्स्ट। |
| `required` | नहीं | `true` खाली फ़ील्ड को गायब चिह्नित करता है और उसका **Clear** बटन छिपा देता है। Oleafly आर्ग्युमेंट खुद कभी नहीं जोड़ता। |
| `default` | नहीं | वह वैल्यू जो आपका फ़ंक्शन तब इस्तेमाल करता है जब आर्ग्युमेंट छोड़ दिया जाए। वह दिखाई जाती है, कभी लिखी नहीं जाती। |

प्रकार और उनकी अतिरिक्त कुंजियाँ:

- `text` एक Typst स्ट्रिंग लिखता है। बड़े बॉक्स के लिए `multiline = true` जोड़ें।
- `content` Typst मार्कअप संपादित करता है और उसे `[...]` ब्लॉक के रूप में लिखता है। स्ट्रिंग आर्ग्युमेंट स्ट्रिंग ही रहता है।
- `choice` को `options` चाहिए: स्ट्रिंग की सूची, या `{ value, label }` टेबल जब लेबल वैल्यू से अलग हो। वैल्यू स्ट्रिंग के रूप में लिखी जाती हैं।
- `number` में `integer`, `min`, `max` और `step` होते हैं। संख्याओं की कोई इकाई नहीं होती।
- `toggle` `true` या `false` लिखता है।

## किन कॉल को फ़ॉर्म मिलता है

Oleafly फ़ाइल के टॉप लेवल पर रिपोर्ट की अपनी `#import` और `#let` लाइनों का पालन करता है:

- `#import "@local/acme-report:0.1.0" as acme` `#acme.info-box(...)` को फ़ॉर्म बनाता है।
- `#import "@local/acme-report:0.1.0": info-box, status-badge as badge` `#info-box(...)` और `#badge(...)` को फ़ॉर्म बनाता है।
- `#import "@local/acme-report:0.1.0": *` पैकेज जिस हर फ़ंक्शन के लिए फ़ॉर्म घोषित करता है, उसे फ़ॉर्म बनाता है।
- `#import "template/memo.typ": memo-header` उस प्रोजेक्ट फ़ॉर्म से मेल खाता है जिसका `module` `template/memo.typ` है। पाथ रिपोर्ट के अपने फ़ोल्डर से पढ़े जाते हैं, या प्रोजेक्ट रूट से जब वे `/` से शुरू हों।

पैकेज का संस्करण ठीक-ठीक मेल खाना चाहिए। फ़ाइल में बाद में आने वाला उसी नाम का `#let` उस बिंदु से आगे फ़ॉर्म को बदल देता है। जिन कॉल तक कोई दूसरी फ़ाइल पहुँचती है जो पैकेज को दोबारा इम्पोर्ट करती है, वे अपना सोर्स टेक्स्ट बनाए रखती हैं।

ऐसा फ़ंक्शन जिसका नाम किसी ऐसे Typst एलिमेंट जैसा हो जिसे Visual mode पहले से बनाता है, जैसे `table` या `figure`, अपने सादे नाम से कॉल होने पर बिल्ट-इन रूप बनाए रखता है। `#acme.table(...)` या नाम बदला हुआ इम्पोर्ट फिर भी फ़ॉर्म पाता है।

## रीड-ओनली दिखने वाले फ़ील्ड

कुछ आर्ग्युमेंट फ़ॉर्म से सुरक्षित रूप से संपादित नहीं किए जा सकते। उनकी पंक्ति कारण के साथ सोर्स दिखाती है, और **Edit in source** उस तक ले जाता है:

- **Computed in the source:** वैल्यू एक एक्सप्रेशन है, जैसे `title: data.title`।
- **Written as a different kind of value:** उदाहरण के लिए जहाँ फ़ॉर्म टेक्स्ट की उम्मीद करता है वहाँ संख्या।
- **Not one of the choices:** ऐसी वैल्यू जो आपके `options` में नहीं है।
- **स्प्रेड आर्ग्युमेंट से सेट:** `..args` वाली कॉल ऐसी वैल्यू देती है जो फ़ॉर्म नहीं देख सकता, इसलिए हर फ़ील्ड रीड-ओनली है।

जब किसी फ़ील्ड को उसकी जगह पर नहीं जोड़ा जा सकता, उदाहरण के लिए किसी गायब आर्ग्युमेंट के बाद का पोज़िशनल आर्ग्युमेंट, तो फ़ॉर्म यह बता देता है और **Add in source** देता है।

## परिभाषा में गलतियाँ

`oleafly-forms.toml`, या वेंडर किए पैकेज की `typst.toml`, को Oleafly में खोलें और हर समस्या अपनी लाइन पर एक मार्कर के रूप में दिखती है: अज्ञात प्रकार, गायब लेबल, डुप्लिकेट फ़ॉर्म, प्रोजेक्ट के बाहर का `module`। टूटा हुआ फ़ॉर्म छोड़ दिया जाता है और बाकी काम करते रहते हैं। 256 KB से बड़ी फ़ाइल नहीं पढ़ी जाती।

## टेम्पलेट साझा करना

Oleafly पैकेज फ़ॉर्म उन्हीं फ़ोल्डरों से पढ़ता है जिन्हें कंपाइलर इस्तेमाल करता है। जिस सहयोगी के पास `@local` पैकेज नहीं है, उसे सादा सोर्स दिखता है और कोई त्रुटि नहीं। प्रोजेक्ट पर सभी के साथ फ़ॉर्म साझा करने के लिए, **Typst packages** डायलॉग खोलें, **Use packages from the project folder** चालू करें और **Vendor packages into project** चुनें। तब पैकेज, और उसके फ़ॉर्म, प्रोजेक्ट के `typst-packages` फ़ोल्डर में साथ चलते हैं ([Typst प्रोजेक्ट](/docs/typst/) देखें)।