_meta.lua

---@meta
---@alias OrgAgendaSpan 'day' | 'week' | 'month' | 'year' | number
---@alias OrgMappingValue string | string[]

---@class OrgAgendaCustomCommandTypeInterface
---@field type? 'agenda' | 'tags' | 'tags_todo'
---@field org_agenda_overriding_header? string
---@field org_agenda_files? string[]
---@field org_agenda_tag_filter_preset? string
---@field org_agenda_category_filter_preset? string
---@field org_agenda_sorting_strategy? OrgAgendaSortingStrategy[]
---@field org_agenda_remove_tags? boolean

---@class OrgAgendaCustomCommandAgenda:OrgAgendaCustomCommandTypeInterface
---@field org_agenda_span? OrgAgendaSpan Default: 'week'
---@field org_agenda_start_day? string Modifier from today, example '+1d'
---@field org_agenda_start_on_weekday? number | false

---@class OrgAgendaCustomCommandTags:OrgAgendaCustomCommandTypeInterface
---@field match? string
---@field org_agenda_todo_ignore_scheduled? OrgAgendaTodoIgnoreScheduledTypes
---@field org_agenda_todo_ignore_deadlines? OrgAgendaTodoIgnoreDeadlinesTypes

---@alias OrgAgendaCustomCommandType (OrgAgendaCustomCommandAgenda | OrgAgendaCustomCommandTags)

---@class OrgAgendaCustomCommand
---@field description string Description in prompt
---@field types? OrgAgendaCustomCommandType[]

---@class OrgCustomExport
---@field label string
---@field action function(fun(cmd: string[], target: string, on_success: function, on_error: function))

---@class OrgCalendarSettings
---@field round_min_with_hours? boolean Should minutes be rounded to hour when changing hour. Default: true
---@field min_small_step? number Step size for changing the minutes while cursor is on the second digit. Default: value of `org_time_stamp_rounding_minutes` = 5
---@field min_big_step? number Step size for changing the minutes while cursor is on the first digit. Default: 15

---@class OrgNotificationsConfig
---@field enabled? boolean Enable notifications. Default: false
---@field cron_enabled? boolean Enable cron notifications. Default: true
---@field repeater_reminder_time? boolean | number | number[] Number of minutes before the repeater time to send the notifiaction. Default: false
---@field deadline_warning_reminder_time? boolean | number | number[] Number of minutes before the deadline wrning time to send the notifiaction. Default: 0
---@field reminder_time? boolean | number | number[] Number of minutes before the time to send the notifiaction. Default: 10
---@field deadline_reminder? boolean Enable notifiactions for DEADLINE dates. Default: true
---@field scheduled_reminder? boolean Enable notifiactions for DEADLINE dates. Default: true

---@class OrgMappingsGlobal
---@field org_agenda? OrgMappingValue Mappings used to open agenda prompt. Default: '<prefix>a'
---@field org_capture? OrgMappingValue Mappings used to open capture prompt. Default: '<prefix>c'

---@class OrgHyperlinksConfig
---@field sources OrgLinkType[]

---@class OrgMappingsAgenda
---@field org_agenda_later? OrgMappingValue Default: 'f'
---@field org_agenda_earlier? OrgMappingValue Default: 'b'
---@field org_agenda_goto_today? OrgMappingValue Default: '.'
---@field org_agenda_day_view? OrgMappingValue Default: 'vd'
---@field org_agenda_week_view? OrgMappingValue Default: 'vw'
---@field org_agenda_month_view? OrgMappingValue Default: 'vm'
---@field org_agenda_year_view? OrgMappingValue Default: 'vy'
---@field org_agenda_quit? OrgMappingValue Default: 'q'
---@field org_agenda_switch_to? OrgMappingValue Default: '<CR>'
---@field org_agenda_goto? OrgMappingValue Default: '<TAB>'
---@field org_agenda_goto_date? OrgMappingValue Default: 'J'
---@field org_agenda_redo? OrgMappingValue Default: 'r'
---@field org_agenda_todo? OrgMappingValue Default: 't'
---@field org_agenda_clock_goto? OrgMappingValue Default: '<prefix>xj'
---@field org_agenda_set_effort? OrgMappingValue Default: '<prefix>xe'
---@field org_agenda_clock_in? OrgMappingValue Default: 'I'
---@field org_agenda_clock_out? OrgMappingValue Default: 'O'
---@field org_agenda_clock_cancel? OrgMappingValue Default: 'X'
---@field org_agenda_clockreport_mode? OrgMappingValue Default: 'R'
---@field org_agenda_priority? OrgMappingValue Default: '<prefix>,'
---@field org_agenda_priority_up? OrgMappingValue Default: '+'
---@field org_agenda_priority_down? OrgMappingValue Default: '-'
---@field org_agenda_archive? OrgMappingValue Default: '<prefix>$'
---@field org_agenda_toggle_archive_tag? OrgMappingValue Default: '<prefix>A'
---@field org_agenda_set_tags? OrgMappingValue Default: '<prefix>t'
---@field org_agenda_deadline? OrgMappingValue Default: '<prefix>id'
---@field org_agenda_schedule? OrgMappingValue Default: '<prefix>is'
---@field org_agenda_filter? OrgMappingValue Default: '/'
---@field org_agenda_refile? OrgMappingValue Default: '<prefix>r'
---@field org_agenda_add_note? OrgMappingValue Default: '<prefix>na'
---@field org_agenda_show_help? OrgMappingValue Default: 'g?'
---
---@class OrgMappingsCapture
---@field org_capture_finalize? OrgMappingValue Default: '<C-c>'
---@field org_capture_refile? OrgMappingValue Default: '<prefix>r'
---@field org_capture_kill? OrgMappingValue Default: '<prefix>k'
---@field org_capture_show_help? OrgMappingValue Default: 'g?'
---
---@class OrgMappingsNote
---@field org_note_finalize? OrgMappingValue Default: '<C-c>'
---@field org_note_kill? OrgMappingValue Default: '<prefix>k'
---
---@class OrgMappingsOrg
---@field org_refile? OrgMappingValue Default: '<prefix>r'
---@field org_timestamp_up_day? OrgMappingValue Default: '<S-UP>'
---@field org_timestamp_down_day? OrgMappingValue Default: '<S-DOWN>'
---@field org_timestamp_up? OrgMappingValue Default: '<C-a>'
---@field org_timestamp_down? OrgMappingValue Default: '<C-x>'
---@field org_change_date? OrgMappingValue Default: 'cid'
---@field org_priority? OrgMappingValue Default: '<prefix>,'
---@field org_priority_up? OrgMappingValue Default: 'ciR'
---@field org_priority_down? OrgMappingValue Default: 'cir'
---@field org_todo? OrgMappingValue Default: 'cit'
---@field org_todo_prev? OrgMappingValue Default: 'ciT'
---@field org_toggle_checkbox? OrgMappingValue Default: '<C-Space>'
---@field org_toggle_heading? OrgMappingValue Default: '<prefix>*'
---@field org_open_at_point? OrgMappingValue Default: '<prefix>o'
---@field org_edit_special? OrgMappingValue Default: "<prefix>'"
---@field org_add_note? OrgMappingValue Default: '<prefix>na'
---@field org_cycle? OrgMappingValue Default: '<TAB>'
---@field org_global_cycle? OrgMappingValue Default: '<S-TAB>'
---@field org_archive_subtree? OrgMappingValue Default: '<prefix>$'
---@field org_set_tags_command? OrgMappingValue Default: '<prefix>t'
---@field org_toggle_archive_tag? OrgMappingValue Default: '<prefix>A'
---@field org_do_promote? OrgMappingValue Default: '<<'
---@field org_do_demote? OrgMappingValue Default: '>>'
---@field org_promote_subtree? OrgMappingValue Default: '<s'
---@field org_demote_subtree? OrgMappingValue Default: '>s'
---@field org_meta_return? OrgMappingValue Add heading, item or row (context-dependent) Default: '<Leader><CR>'
---@field org_return? OrgMappingValue Default: '<CR>'
---@field org_insert_heading_respect_content? OrgMappingValue Add new heading after current heading block (same level) Default: '<prefix>ih'
---@field org_insert_todo_heading? OrgMappingValue Add new todo heading right after current heading (same level) Default: '<prefix>iT'
---@field org_insert_todo_heading_respect_content? OrgMappingValue Add new todo heading after current heading block (same level). Default: '<prefix>it'
---@field org_move_subtree_up? OrgMappingValue Default: '<prefix>K'
---@field org_move_subtree_down? OrgMappingValue Default: '<prefix>J'
---@field org_export? OrgMappingValue Default: '<prefix>e'
---@field org_next_visible_heading? OrgMappingValue Default: '}'
---@field org_previous_visible_heading? OrgMappingValue Default: '{'
---@field org_forward_heading_same_level? OrgMappingValue Default: ']]'
---@field org_backward_heading_same_level? OrgMappingValue Default: '[['
---@field outline_up_heading? OrgMappingValue Default: 'g{'
---@field org_deadline? OrgMappingValue Default: '<prefix>id'
---@field org_schedule? OrgMappingValue Default: '<prefix>is'
---@field org_time_stamp? OrgMappingValue Default: '<prefix>i.'
---@field org_time_stamp_inactive? OrgMappingValue Default: '<prefix>i!'
---@field org_toggle_timestamp_type? OrgMappingValue Default: '<prefix>d!'
---@field org_insert_link? OrgMappingValue Default: '<prefix>li'
---@field org_store_link? OrgMappingValue Default: '<prefix>ls'
---@field org_clock_in? OrgMappingValue Default: '<prefix>xi'
---@field org_clock_out? OrgMappingValue Default: '<prefix>xo'
---@field org_clock_cancel? OrgMappingValue Default: '<prefix>xq'
---@field org_clock_goto? OrgMappingValue Default: '<prefix>xj'
---@field org_set_effort? OrgMappingValue Default: '<prefix>xe'
---@field org_show_help? OrgMappingValue Default: 'g?'
---@field org_babel_tangle? OrgMappingValue Default: '<prefix>bt'

---@class OrgMappingsTextObjects
---@field inner_heading? OrgMappingValue Default: 'ih'
---@field around_heading? OrgMappingValue Default: 'ah'
---@field inner_subtree? OrgMappingValue Default: 'ir'
---@field around_subtree? OrgMappingValue Default: 'ar'
---@field inner_heading_from_root? OrgMappingValue Default: 'Oh'
---@field around_heading_from_root? OrgMappingValue Default: 'OH'
---@field inner_subtree_from_root? OrgMappingValue Default: 'Or'
---@field around_subtree_from_root? OrgMappingValue Default: 'OR'
---
---@class OrgMappingsEditSrc
---@field org_edit_src_abort? OrgMappingValue Default: '<prefix>k'
---@field org_edit_src_save? OrgMappingValue Default: '<prefix>w'
---@field org_edit_src_save_exit? OrgMappingValue Default: "<prefix>'"
---@field org_edit_src_show_help? OrgMappingValue Default: 'g?'
---
---@class OrgEmacsConfig
---@field executable_path? string path to emacs executable. Default: 'emacs'
---@field config_path? string | nil path to emacs config file. If nil, attempts to find the config automatically. Default: nil
---

---@class OrgUiConfig
---@field folds? { colored: boolean } Should folds be colored or use the default folding highlight. Default: { colored: true }
---@field menu? { handler: fun() | nil } Menu configuration
---@field input? { use_vim_ui: boolean } Input configuration

---@class OrgMappingsConfig
---@field disable_all? boolean Disable all mappings. Default: false
---@field org_return_uses_meta_return? boolean When true, `<CR>` will act as `<Leader><CR>` when applicable. Default: false
---@field prefix? string Default prefix for mappings. Default: '<Leader>o'
---@field global? OrgMappingsGlobal
---@field agenda? OrgMappingsAgenda
---@field capture? OrgMappingsCapture
---@field note? OrgMappingsNote
---@field edit_src? OrgMappingsEditSrc
---@field org? OrgMappingsOrg
---@field text_objects? OrgMappingsTextObjects

---@class OrgConfigOpts
---@field org_agenda_files? string | string[] Path(s) to org files. Can be a glob pattern (example: `~/org/**/*`). Default: {}
---@field org_default_notes_file? string Path to default file for captures. Default: ''
---@field org_todo_keywords? string[] List of todo/done states, separated by `|`. Default: { 'TODO', '|', 'DONE' }
---@field org_todo_repeat_to_state? string | nil An `org_todo_keywords` todo entry to use as a "starting" state for repeatable todos. Defaults to first todo state
---@field org_todo_keyword_faces? table<string, string> Custom faces (colors) for todo keywords. Default: {}
---@field org_deadline_warning_days? number Number of days during which deadline becomes visible in today's agenda. Default: 14
---@field org_agenda_min_height? number Minimum height of the agenda window. Default: 16
---@field org_agenda_span? OrgAgendaSpan Default time span for the agenda view. Default: 'week'
---@field org_agenda_start_on_weekday? number | false From which day in week (ISO weekday, 1 is Monday) to show the agenda. Applies only to `week` span. Default: 1
---@field org_agenda_start_day? string | nil Offset applied to the `org_agenda_start_on_weekday` in format `+1d`, `+2w`, etc. Default: nil
---@field calendar_week_start_day? 0 | 1 From which day to start the week in the Calendar. 0 is Sunday, 1 is Monday. Default: 1
---@field calendar? OrgCalendarSettings Calendar settings
---@field org_capture_templates? table<string, OrgCaptureTemplateOpts> Templates for capture. Default: { t = { description = 'Task', template = '* TODO %?\n  %u' } }
---@field org_startup_folded? 'overview' | 'content' | 'showeverything' |'inherit' How many levels of headings to show when opening a file. Default: 'overview'
---@field org_agenda_skip_scheduled_if_done? boolean If true, scheduled entries marked as done will not be shown in the agenda. Default: false
---@field org_agenda_skip_deadline_if_done? boolean If true, deadline entries marked as done will not be shown in the agenda. Default: false
---@field org_agenda_text_search_extra_files? ('agenda-archives')[] Additional files to earch from agenda search prompt. Default: {}
---@field org_agenda_custom_commands? table<string, OrgAgendaCustomCommand> Custom commands for the agenda view. Default: {}
---@field org_agenda_block_separator? string Separator for blocks in the agenda view. Default: '-'
---@field org_agenda_sorting_strategy? table<'agenda' | 'todo' | 'tags', OrgAgendaSortingStrategy[]> Sorting strategy for the agenda view. See docs for default value
---@field org_agenda_remove_tags? boolean If true, tags will be removed from the all agenda views. Default: false
---@field org_priority_highest? string | number Highest priority level. Default: 'A'
---@field org_priority_default? string | number Default priority level. Default: 'B'
---@field org_priority_lowest? string | number Lowest priority level. Default: 'C'
---@field org_priority_start_cycle_with_default? boolean If true, cycling priorities will start with the default priority. Default: true
---@field org_archive_location? string Location where to archive subtrees. `%s` indicates the file name from where archiving is done. Default: '%s_archive::'
---@field org_tags_column? number Padding for tags column. Negative indicates how many columns to pad from headline. Positive indicates specific column. Default: -80
---@field org_use_tag_inheritance? boolean If true, tags will be inherited from parent headlines. Default: true
---@field org_tags_exclude_from_inheritance? string[] List of tags that should be excluded from tag inheritance. Default: {}
---@field org_hide_leading_stars? boolean If true, leading stars on the headlines with level > 1 will be hidden. Default: false
---@field org_hide_emphasis_markers? boolean If true, emphasis markers will be hidden with conceal feature. Default: false
---@field org_ellipsis? string Ellipsis character to use when folding text. Default: '...'
---@field org_log_done? 'time' | 'note' How to log done tasks. `time` indicates adding CLOSED date. `note` prompts for closing note. Default: 'time'
---@field org_log_repeat? 'time' | 'note' | false How to log repeated tasks. `time` just logs the time of repeat. `note` prompts for closing note alongside the time. `false` disables. Default: 'time'
---@field org_log_into_drawer? string | nil Drawer name where to log notes. Default: nil
---@field org_highlight_latex_and_related? 'native' | 'entities' | nil What level of latex highlighting to use. This option is experimental. Default: nil
---@field org_custom_exports? table<string, OrgCustomExport> List of custom exports. Default: {}
---@field org_adapt_indentation? boolean Add spaces as indents to the content. Default: true
---@field org_startup_indented? boolean If true, apply virtual indents to the content. Default: false
---@field org_indent_mode_turns_off_org_adapt_indentation? boolean If true, turning on indent mode will turn off `org_adapt_indentation`. Default: true
---@field org_indent_mode_turns_on_hiding_stars? boolean If true, turning on indent mode will hide leading stars. Default: true
---@field org_time_stamp_rounding_minutes? number Rounding minutes for time stamps. Default: 5
---@field org_cycle_separator_lines? number Min number of spaces are needed at the end of headline to show empty line between folds. Default: 2
---@field org_blank_before_new_entry? { heading: boolean, plain_list_item: boolean } Should blank line be prepended. Default: { heading = true, plain_list_item = false }
---@field org_src_window_setup? string | fun() How to open "special edit" buffer window. Default: 'top 16new'
---@field org_edit_src_content_indentation? number Addditional ndentation number applied when editing a SRC block through special edit. Default: 0
---@field org_id_uuid_program? string External proram to generate UUIDs. Default: 'uuidgen'
---@field org_id_ts_format? string  Format of the id generated when `org_id_method = 'ts'`. Default: '%Y%m%d%H%M%S'
---@field org_id_method? 'uuid' | 'ts' | 'org' What method to use to generate ids via org.id module. Default: 'uuid'
---@field org_id_prefix? string | nil Prefix to apply to id when `org_id_method = 'org'`. Default: nil
---@field org_id_link_to_org_use_id? boolean If true, Storing a link to the headline will automatically generate ID for that headline. Default: false
---@field org_use_property_inheritance boolean | string | string[] If true, properties are inherited by sub-headlines; may also be a regex or list of property names. Default: false
---@field org_babel_default_header_args? table<string, string> Default header args for org-babel blocks: Default: { [':tangle'] = 'no', [':noweb'] = 'no' }
---@field win_split_mode? 'horizontal' | 'vertical' | 'auto' | 'float' | string[] How to open agenda and capture windows. Default: 'horizontal'
---@field win_border? 'none' | 'single' | 'double' | 'rounded' | 'solid' | 'shadow' | string[] Border configuration for `win_split_mode = 'float'`. Default: 'single'
---@field notifications? OrgNotificationsConfig Notification settings
---@field mappings? OrgMappingsConfig Mappings configuration
---@field emacs_config? OrgEmacsConfig Emacs cnfiguration
---@field ui? OrgUiConfig UI configuration
---@field hyperlinks OrgHyperlinksConfig  Custom sources for hyperlinks